使用 PHP 建構應用程式

瞭解如何使用 PHP 7.4 或 8.1 版，在 App Engine 中建構應用程式。 使用者可以透過範例應用程式，將喜愛書籍的書名、作者、說明、出版日期和圖片發布到網頁。應用程式會將文字資料儲存在 Cloud SQL 資料庫中，圖片則儲存在 Cloud Storage bucket 中。

指南結構

1. 使用 Google Cloud CLI 建立專案 Google Cloud

2. 下載範例應用程式

3. 使用 composer.json 指定依附元件

4. 初始化應用程式並定義前端控制器

5. 與 Google Cloud 服務整合

6. 設定 App Engine 應用程式

7. 部署應用程式

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，能用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

1. 安裝 Composer，這是 PHP 依附元件管理工具。您必須在 Linux 和 Mac OS X 系統上全域安裝 Composer。
2. 由於新專案中服務帳戶的預設使用方式異動，以及預設安全機構政策異動，您可能需要將額外角色授予部署服務帳戶。如要進一步瞭解如何授予特定角色，請參閱疑難排解指南。

下載範例應用程式

1. 在 GitHub 探索程式碼

2. 下載或複製應用程式。

   git clone https://github.com/GoogleCloudPlatform/php-docs-samples.git

   您也可以下載 zip 格式的範例檔案，然後將檔案解壓縮。

3. 前往 getting-started 目錄。

   cd php-docs-samples/appengine/standard/getting-started

使用 composer.json 指定依附元件

應用程式會使用前端控制器來轉送要求。本指南中的程式碼範例使用 Slim Framework，但您可以自由使用您選擇的網路架構。

1. 開啟 composer.json 檔案，查看所有直接依附元件：

   {
     "require": {
       "google/cloud-storage": "^1.6",
       "slim/slim": "^4.0",
       "slim/psr7": "^1.0",
       "slim/twig-view": "^3.0",
       "php-di/slim-bridge": "^3.1",
       "symfony/yaml": "^5.2"
     },
     "autoload": {
        "psr-4": {
          "Google\\Cloud\\Samples\\AppEngine\\GettingStarted\\": "src"
        }
     }
   }
   

2. 如要安裝依附元件並產生 composer.lock 檔案，請執行下列指令：

   composer install
   

   composer.lock 檔案可協助應用程式在多個建構作業和環境中，擷取相同版本的套件。

初始化應用程式並定義前端控制器

index.php 檔案會初始化應用程式，並將所有要求轉送至 ./src/controllers.php 檔案中定義的控制器。

// Use the composer autoloader to load dependencies.
require_once __DIR__ . '/vendor/autoload.php';

//  Load the application code.
/** @var Slim\App $app */
$app = require __DIR__ . '/src/app.php';
require __DIR__ . '/src/controllers.php';

// Bootstrap the slim framework to handle the request.
$app->run();

如要進一步瞭解如何處理要求，請參閱「應用程式啟動」和「處理要求」。

與 Google Cloud 服務整合

App Engine 規定應用程式必須整合外部系統，才能儲存資料。 範例應用程式會將文字資料儲存在 Cloud SQL， 圖片則儲存在 Cloud Storage。

如要查看所有 Google Cloud 儲存空間選項，請參閱「選擇儲存空間選項」頁面。

使用 Cloud SQL

在範例應用程式中，使用者會將書籍張貼到網頁中。應用程式會使用 Cloud SQL 資料庫儲存書籍的書名、作者、出版日期與說明。

您必須先建立 Cloud SQL 執行個體，才能將內容新增至應用程式的資料庫。

建立 Cloud SQL 執行個體

使用 gcloud CLI 建立 Cloud SQL 執行個體：

gcloud sql instances create INSTANCE_NAME --tier=MACHINE_TYPE --region=REGION

舉例來說，如要將執行個體命名為 bookshelf，並在美國中部區域使用 db-n1-standard-2 的機器類型：

gcloud sql instances create bookshelf --tier=db-n1-standard-2 --region=us-central1

設定 MySQL 超級使用者

您可以使用 gcloud CLI 設定 Cloud SQL 執行個體的超級使用者密碼：

gcloud sql users set-password USER --host=HOST --instance=INSTANCE_NAME --password=PASSWORD

舉例來說，如要將 Cloud SQL 執行個體 bookshelf 的超級使用者密碼設為 passw0rd!，請執行下列指令：

gcloud sql users set-password root --host=% --instance=bookshelf --password=passw0rd!

在 Cloud SQL 執行個體上設定資料庫

如要儲存書籍的作者、書名、出版日期與說明，請建立 MySQL 資料庫：

gcloud sql databases create DATABASE_NAME --instance=INSTANCE_NAME

舉例來說，如要在 Cloud SQL 執行個體 bookshelf 上建立名為 book-data 的資料庫：

gcloud sql databases create book-data --instance=bookshelf

連線至 Cloud SQL 資料庫

範例應用程式使用 PHP 的 PDO 與 MySQL 資料庫互動。

// Fill the variables below to match your Cloud SQL configuration.
// $dbConn = 'YOUR_CLOUDSQL_CONNECTION_NAME';
// $dbName = 'YOUR_CLOUDSQL_DATABASE_NAME';
// $dbUser = 'YOUR_CLOUDSQL_USER';
// $dbPass = 'YOUR_CLOUDSQL_PASSWORD';
$dsn = "mysql:unix_socket=/cloudsql/{$dbConn};dbname={$dbName}";
$pdo = new PDO($dsn, $dbUser, $dbPass);

在本教學課程中，這些參數在下方的設定應用程式一節中會指定為環境變數。

查詢單一資料列

使用者按一下書籍時，應用程式會查詢資料庫，並傳回包含書籍標題、作者、出版日期與說明的單一資料列。

$statement = $pdo->prepare('SELECT * FROM books WHERE id = :id');
$statement->bindValue('id', $id, PDO::PARAM_INT);
$statement->execute();
$result = $statement->fetch(PDO::FETCH_ASSOC);

使用 Cloud Storage

範例應用程式會使用 Cloud Storage 儲存圖片，這些圖片是使用者上傳的二進位檔案。

建立 Cloud Storage bucket

Cloud Storage 使用值區組織及控管資料的存取權。

使用 gcloud CLI 建立 Cloud Storage bucket：

gcloud storage buckets create gs://BUCKET_NAME/ --location=BUCKET_REGION

舉例來說，如要在 us-central1 區域中建立名為 picture-storage 的 bucket，請執行下列指令：

gcloud storage buckets create gs://picture-storage/ --location=us-central1

• 如果成功，您會看到下列輸出內容：

  Creating gs://BUCKET_NAME/

• 如果不成功，您可能會看到下列輸出內容：

  ServiceException: 409 Bucket BUCKET_NAME already exists

  請使用其他值區名稱再試一次。

將專案連結至 Cloud Storage bucket

如要使用 Cloud Storage，您必須指定 Cloud Storage 程式庫。

use Google\Cloud\Storage\StorageClient;

儲存圖片

您已建立 Cloud Storage bucket 並設定連線，現在可以儲存圖片。您可以使用預先定義的存取控制清單 (ACL) 上傳圖片，藉此控管圖片的存取權。

在這個範例應用程式中，上傳的圖片會具有預先定義的 ACL public-read。您可以透過 Cloud Storage 物件的 mediaLink 屬性存取公開網址。您可以在 HTML 圖片標記中使用這個網址。

// Set your own image file path and content type below to upload an
// image to Cloud Storage.
// $imageStream = fopen('/path/to/your_image.jpg', 'r');
// $imageContentType = 'image/jpg';
$object = $bucket->upload($imageStream, [
    'metadata' => ['contentType' => $imageContentType],
    'predefinedAcl' => 'publicRead',
]);
$imageUrl = $object->info()['mediaLink'];

如需讀取私有 Cloud Storage 物件的操作說明，請參閱「下載物件」頁面。

刪除圖片

使用者從應用程式刪除書籍時，這段程式碼會從 Cloud Storage bucket 移除圖片。

$object = $bucket->object($objectName);
$object->delete();

設定應用程式

您可以使用 app.yaml 檔案將應用程式設定為在 App Engine 上執行，該檔案可指定應用程式的執行階段、環境變數及其他設定。

如果應用程式的設定需求極少，app.yaml 檔案可以只有一行：

runtime: php81

runtime: php74

您可以在 app.yaml 設定檔中新增其他設定選項和應用程式專屬的環境變數。

新增環境變數

應用程式會從 app.yaml 檔案取得環境設定。本指南使用的 Bookshelf 範例需要以環境變數的形式提供設定，才能瞭解如何連線至正確的 Cloud SQL 執行個體和 Cloud Storage 儲存空間。

如要部署應用程式，請編輯 app.yaml 設定檔：

# See https://cloud.google.com/appengine/docs/standard/php/config/appref for a
# complete list of `app.yaml` directives.

runtime: php84

env_variables:
    GOOGLE_STORAGE_BUCKET: ""
    # populate these to use the "mysql" or "postres" backends
    CLOUDSQL_CONNECTION_NAME: ""
    CLOUDSQL_USER: ""
    CLOUDSQL_PASSWORD: ""
    ## Uncomment to give your database a name other than "bookshelf"
    # CLOUDSQL_DATABASE_NAME: ""

1. 將 GOOGLE_STORAGE_BUCKET 變數設定為 Cloud Storage 值區的名稱。

2. 將 CLOUDSQL_CONNECTION_NAME 變數設為 app-name:region:instance-name 您可以使用下列 gcloud 指令擷取必要詳細資料：

   gcloud sql instances describe INSTANCE

   如果是 Cloud SQL 第二代執行個體，CLOUDSQL_CONNECTION_NAME 的格式如下：your_project_name:your_region:your_instance

3. 如果您建立的資料庫名稱不是 bookshelf，請取消註解並設定 CLOUD_SQL_DATABASE_NAME 變數。在本例中，資料庫是以「book-data」為名建立。

4. 檢查 app.yaml 檔案，內容應如下所示：

runtime: php81

env_variables:
  GOOGLE_STORAGE_BUCKET: picture-storage
  CLOUDSQL_CONNECTION_NAME: sample-application:us-central1:bookshelf
  CLOUDSQL_USER: root
  CLOUDSQL_PASSWORD: passw0rd!
  CLOUDSQL_DATABASE_NAME: book-data

runtime: php74

env_variables:
  GOOGLE_STORAGE_BUCKET: picture-storage
  CLOUDSQL_CONNECTION_NAME: sample-application:us-central1:bookshelf
  CLOUDSQL_USER: root
  CLOUDSQL_PASSWORD: passw0rd!
  CLOUDSQL_DATABASE_NAME: book-data

部署應用程式

1. 如要部署應用程式，請前往 getting-started 目錄，然後執行下列指令：

   gcloud app deploy

2. 位置提示出現時，請選擇應用程式使用者附近的位置。 App Engine 具有「地區性」，這表示執行您應用程式的基礎架構位於特定地理區域。舉例來說，本教學課程已使用 us-central1 區域部署儲存空間資源。在相同區域中部署應用程式，縮短延遲時間並提升效能。

   一般而言，我們會建議您選擇靠近使用者的位置，但有時將應用程式部署在靠近其資源的位置也是合適的做法。請參閱這篇文章，瞭解可用的 App Engine 位置，以及這篇文章，瞭解資源位置。

3. 查看應用程式：

   gcloud app browse

清除所用資源

刪除 Google Cloud 專案，停止對專案中使用的資源計費。

如要刪除您的專案，請使用下列指令：

gcloud projects delete PROJECT_ID

如要確認專案已刪除，請列出您的專案：

gcloud projects list

後續步驟

• 瞭解如何驗證使用者。
• 如要進一步瞭解如何寫入應用程式記錄及解讀系統記錄，請參閱「讀取及寫入應用程式記錄」。
• 瞭解如何使用 Cloud Tasks 在要求後以非同步方式在背景執行工作。
• 請參閱要求處理和要求路徑。
• 如要深入瞭解 App Engine 的運作方式，請參閱「PHP 執行階段環境」。