PHP 執行階段環境

PHP 執行階段是一個軟體堆疊，負責安裝網路服務的程式碼和其依附元件，並執行服務。

如要為 App Engine 標準環境指定 PHP，請在 app.yaml 檔案中宣告執行階段。例如：

runtime: phpVERSION

其中 VERSION 是 PHP MAJOR 和 MINOR 版本號碼。舉例來說，如要使用最新 PHP 版本 (PHP 8.5)，請指定 85。

如要瞭解其他支援的 PHP 版本，以及 PHP 版本對應的 Ubuntu 版本，請參閱「執行階段支援時間表」。

PHP 版本

最新支援的 PHP 版本為 8.5。PHP 執行階段會使用 app.yaml 檔案中指定版本的最新穩定版。App Engine 會自動更新至新的修補程式版本，但不會自動更新次要版本。

舉例來說，您的應用程式可能先採用 PHP 7.3.0 版進行部署，並在之後自動更新成 7.3.1 版，但是並不會自動更新至 PHP 7.4.0。

注意： 如果 composer.json 檔案中指定必要的 PHP 版本，則必須移除該元素才能成功部署。

應用程式啟動

您需要部署前端控制器來處理所有要求轉送作業。

以下範例說明提供應用程式的不同方式：

• 如果應用程式包含 public/index.php 或 index.php 檔案，App Engine 會使用這個檔案提供應用程式。

  建議您使用 Laravel、Symfony 或 Slim 等架構，因為這些架構提供輕量轉送功能，可快速地寫入和部署 PHP 應用程式。請參閱範例 Slim 前端控制器一文。

  不過，如果您要遷移舊版應用程式，請參閱下列 index.php 範例檔案，匯入所需的 PHP 檔案並手動實作前端控制器：

  switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
      case '/':
          require 'homepage.php';
          break;
      case '/contact.php':
          require 'contact.php';
          break;
      default:
          http_response_code(404);
          exit('Not Found');
  }

• 如果您在 app.yaml 檔案中指定選用的 entrypoint 元素，App Engine 會使用 entrypoint 元素中的指令來提供應用程式，而不是使用 public/index.php 或 index.php：

      entrypoint: serve path/to/my/front/controller.php
  

  entrypoint 欄位會使用內建的 serve 指令，這是 PHP 執行階段內的一個程式，可在背景啟動 php-fpm 實作與網路伺服器。這個網路伺服器會使用前端控制器設計模式，將所有流量轉送至提供的 PHP 檔案。

  serve 指令有兩個選用旗標：

  • --workers=N：指定 N 個 php-fpm 工作站。如果您沒有設定 --workers 標記，serve 指令會根據可用記憶體量推測工作站數。為獲得最佳結果，請將 serve 指令的 --workers 標記與 max_concurrent_requests 元素的值設定為同一個數目。

  • --enable-dynamic-workers：指定您想讓 php-fpm 工作站僅在需要時產生。預設會針對 php-fpm 工作站使用靜態政策。您可使用 --workers=N 標記，變更產生工作站的數目上限。根據預設，靜態政策會設定產生工作站的預設數目上限。

  選用標記必須在前端控制器路徑的前方：

      entrypoint: serve --workers=2 --enable-dynamic-workers path/to/index.php
  

• 您可以將 entrypoint 元素設定為工作站處理程序的檔案路徑，以部署長時間執行的工作站處理程序：

      entrypoint: php long-running-worker-file.php
  

  如果 entrypoint 元素執行長時間執行處理程序的指令碼，例如訂閱主題的 Pub/Sub 工作站，請勿使用 serve 指令。

詳情請參閱 app.yaml 參考資料 。

啟用的擴充功能

App Engine 的 PHP 執行階段已啟用下列擴充功能：

• BCMath
• bz2
• Calendar
• core
• cgi
• ctype
• cURL
• date
• dba
• dom
• enchant
• Exif
• fcgi
• fileinfo
• filter
• FTP
• GD
• gettext
• GMP
• hash
• iconv
• intl
• json
• LDAP
• libxml
• mbstring
• MYSQLi
• mysqlnd
• MySQL (PDO)
• OPcache
• OpenSSL
• PCNTL
• pcre
• PDO
• pgsql
• Phar
• posix
• PostgreSQL (PDO)
• Reflection
• session
• Shmop
• SimpleXML
• SOAP
• Sockets
• sodium (PHP 8.x only, not available for PHP 7.x)
• SPL
• SQLite (PDO)
• SQLite3
• standard
• test
• tidy
• tokenizer
• XML
• XMLreader
• XMLrpc (PHP 7.x only, not available for PHP 8.x)
• XMLwriter
• XSL
• zend
• Zip
• Zlib

可動態載入的擴充功能

設定 php.ini 後，可動態載入以下擴充功能：

• Memcached
• gRPC
• protobuf
• MongoDB
• ImageMagick
• OpenCensus
• OpenTelemetry
• PHPRedis

如要啟用這些擴充功能，請在 php.ini 檔案的 extension 下方新增相關指令，例如：

extension=memcached.so
extension=grpc.so
extension=protobuf.so
extension=mongodb.so
extension=imagick.so
extension=opencensus.so
extension=redis.so

[opentelemetry]
extension=opentelemetry.so

環境變數

下列為執行階段設定的環境變數：

環境變數	說明
GAE_APPLICATION	App Engine 應用程式的 ID。 這個 ID 的前置字元為「region code~」，例如在歐洲部署的應用程式為「e~」。
GAE_DEPLOYMENT_ID	目前部署的 ID。
GAE_ENV	App Engine 環境。設為 standard。
GAE_INSTANCE	服務目前正在執行的執行個體 ID。
GAE_MEMORY_MB	應用程式程序可用的記憶體量，以 MB 為單位。
GAE_RUNTIME	在 app.yaml 檔案中指定的執行階段。
GAE_SERVICE	在 app.yaml 檔案中指定的服務名稱。如果未指定服務名稱，則會設為 default。
GAE_VERSION	服務目前的版本標籤。
GOOGLE_CLOUD_PROJECT	與應用程式相關聯的 Google Cloud 專案 ID。
PORT	接受 HTTP 要求的通訊埠。
NODE_ENV (僅適用於 Node.js 執行階段)	在部署服務時設定為 production。

您可以在 app.yaml 檔案中定義其他環境變數，但無法覆寫上述值 (NODE_ENV 除外)。

HTTPS 和轉送 Proxy

App Engine 會在負載平衡器上終止 HTTPS 連線，並將要求轉送至您的應用程式。部分應用程式需要判斷原始要求 IP 和通訊協定。使用者的 IP 位址會顯示在標準 X-Forwarded-For 標頭中。需要這項資訊的應用程式應將其網路架構設定為「信任 Proxy」。

檔案系統

執行階段包含可寫入的 /tmp 目錄，其他所有目錄都只有唯讀存取權。寫入 /tmp 會佔用系統記憶體。詳情請參閱 tempnam() 和 sys_get_temp_dir() 支援。

中繼資料伺服器

應用程式的每個執行個體都可以使用 App Engine 中繼資料伺服器來查詢與執行個體和專案相關的資訊。

注意： 標準環境不支援自訂中繼資料。

您可以透過以下端點存取中繼資料伺服器：

• http://metadata
• http://metadata.google.internal

傳送至中繼資料伺服器的要求必須包含要求標頭 Metadata-Flavor: Google。此標頭指示是在擷取中繼資料值的意圖之下傳送要求。

下表列出可讓您針對特定中繼資料發出 HTTP 要求的端點：

中繼資料端點	說明
/computeMetadata/v1/project/numeric-project-id	指派給專案的專案編號。
/computeMetadata/v1/project/project-id	指派給專案的專案 ID。
/computeMetadata/v1/instance/region	執行個體執行的區域。
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email	指派給專案的預設服務帳戶電子郵件。
/computeMetadata/v1/instance/service-accounts/default/	列出專案的所有預設服務帳戶。
/computeMetadata/v1/instance/service-accounts/default/scopes	列出預設服務帳戶的所有支援範圍。
/computeMetadata/v1/instance/service-accounts/default/token	傳回可用來向其他 Google Cloud API 驗證應用程式的驗證憑證。

舉例來說，如要擷取專案 ID，請將要求傳送至 http://metadata.google.internal/computeMetadata/v1/project/project-id。

下列範例說明如何使用 cURL 或 Google Cloud 用戶端程式庫呼叫中繼資料端點：

/**
 * Requests a key from the Metadata server using the Google Cloud SDK. Install
 * the Google Cloud SDK by running "composer install google/cloud"
 *
 * @param $metadataKey the key for the metadata server
 */
function request_metadata_using_google_cloud($metadataKey)
{
    $metadata = new Google\Cloud\Core\Compute\Metadata();
    $metadataValue = $metadata->get($metadataKey);

    return $metadataValue;
}

/**
 * Requests a key from the Metadata server using cURL.
 *
 * @param $metadataKey the key for the metadata server
 */
function request_metadata_using_curl($metadataKey)
{
    $url = 'http://metadata/computeMetadata/v1/' . $metadataKey;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Metadata-Flavor: Google'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    return curl_exec($ch);
}

工作階段

PHP 提供工作階段管理層，可讓網路應用程式保留要求之間的使用者狀態資訊。App Engine 中的工作階段運作方式，與其他 PHP 應用程式中的工作階段非常相似。

如要在使用者工作階段中設定變數，您可以使用下列程式碼：

session_start();
$_SESSION['Foo'] = 'Bar';

在同一位使用者後續的要求中，下列程式碼會列印 Bar：

session_start();
print $_SESSION['Foo']; // prints Bar

對於存在時間較久的工作階段，請使用替代的儲存空間服務，例如 Cloud SQL。

特殊 $_SERVER 鍵

PHP 會在要求範圍中提供特殊的 $_SERVER[] 陣列。除了標準 CGI 參數外，App Engine 還會新增其他一些有用的鍵值。

• GAE_APPLICATION：目前應用程式的 Google Cloud 專案 ID。
• GAE_DEPLOYMENT_ID - 所部署原始碼的 ID。
• GAE_ENV - 執行應用程式的 App Engine 環境 (標準或彈性)。
• GAE_INSTANCE - 目前正在執行的執行個體名稱。
• GAE_MEMORY_MB - 應用程式程序可用的記憶體量，以 MB 為單位。
• GAE_RUNTIME - 在您的 app.yaml 檔案中指定的執行階段，例如 php72。
• GAE_SERVICE - 目前部署的服務名稱。
• GAE_VERSION - 目前部署的版本名稱。
• GOOGLE_CLOUD_PROJECT - Google Cloud 專案 ID。
• HTTP_X_APPENGINE_CITY - 要求來源城市的名稱。例如，如果是來自 Mountain View (山景市) 的要求，標頭值可能為「mountain view」。
• HTTP_X_APPENGINE_CITYLATLONG - 要求來源城市的經緯度。如果是來自 Mountain View (山景市) 的要求，則這個字串看起來可能像「37.386051,-122.083851」。
• HTTP_X_APPENGINE_COUNTRY - 發出要求的來源國家/地區，採用 ISO 3166-1 alpha-2 國家/地區代碼。App Engine 會根據用戶端的 IP 位址決定這個代碼。
• HTTP_X_APPENGINE_HTTPS - 驗證 HTTPS 使用量。
• HTTP_X_APPENGINE_REGION - 要求來源地區的名稱。這個值必須搭配 X-Appengine-Country 中的國家/地區一起理解。舉例來說，如果國家/地區是「US」而地區是「ca」，則「ca」表示「加州」而非加拿大。
• HTTP_X_APPENGINE_USER_IP - 用戶端的 IP 位址。請注意，$_SERVER['HTTP_X_APPENGINE_USER_IP'] 是應用程式擷取用戶端 IP 位址的唯一方式。App Engine 不支援 $_SERVER['REMOTE_ADDR'] 變數。

指令與新的初始化預設值

下表列出初始化預設值與 php.net 提供的標準 PHP 解譯器不同的指令。如要查看下表未列出的指令預設值，請參閱 php.ini 指令。

指令	App Engine 中的預設值
expose_php	Off
memory_limit	-1
max_execution_time	0
error_reporting	E_ALL & ~E_DEPRECATED & ~E_STRICT
display_errors	Off
display_startup_errors	Off
log_errors	On
log_errors_max_len	0
ignore_repeated_errors	Off
ignore_repeated_source	Off
html_errors	Off
opcache.enable	On
opcache.validate_timestamps	Off
opcache.memory_consumption	32

您可以在應用程式的 php.ini 檔案中加入這些預設指令來覆寫這些指令值。

tempnam() 和 sys_get_temp_dir() 支援

App Engine 應用程式是在安全沙箱中執行，只有 /tmp 目錄可寫入，並儲存在執行個體的 RAM 中。因此，App Engine 版本的 tempnam() 會傳回記憶體內的暫存檔，此檔案可以稍後寫入永久儲存空間解決方案，例如 Google Cloud Storage 值區。

以下範例說明如何使用 file_put_contents() 與 fwrite() 寫入記憶體內暫存檔案。

<?php
$dir = sys_get_temp_dir();
$tmp = tempnam($dir, "foo");
file_put_contents($tmp, "hello");
$f = fopen($tmp, "a");
fwrite($f, " world");
fclose($f);
echo file_get_contents($tmp);

預期的範例輸出如下：

hello world

注意： 刪除執行個體時，系統也會一併移除 tempnam() 建立的所有暫存檔案。

使用 Composer 管理依附元件

詳情請參閱指定依附元件頁面。