PHP 執行階段

PHP 執行階段是軟體堆疊，負責安裝應用程式程式碼和依附元件，然後在彈性環境中執行該應用程式。

PHP 版本

PHP 8.4 會使用Buildpack。如需支援的 PHP 版本完整清單，以及對應的 Ubuntu 版本，請參閱執行階段支援時間表。

如要使用支援的 PHP 版本，您必須：

• 安裝 gcloud CLI 420.0.0 以上版本。您可以執行 gcloud components update 指令來更新 CLI 工具。如要查看已安裝的版本，您可以執行 gcloud version 指令。

• 在 app.yaml 檔案中加入 runtime_config 和 operating_system 設定，以指定作業系統。

• 在 app.yaml 檔案中宣告應用程式的文件根目錄：

    runtime: php
    env: flex
  
    runtime_config:
        operating_system: "ubuntu22"
        document_root: "web"
  

  雖然您可以將專案根目錄 (.) 指定為文件根目錄，但建議您為 document_root 設定使用子目錄。

  原始碼位於 /workspace 目錄，而非根目錄 (/)。如果您覆寫任何設定，NGINX 或 supervisor 程序會參照這個目錄中的設定檔。如要更新對應的參照，您必須：

  • 更新 NGINX 設定中的任何 include 陳述式，使其相對於 /workspace 而非 /etc/nginx。

  • 但不包含 gzip_params 等部分檔案。如要參照這些檔案，請加入您自己的檔案或從 GitHub 複製的檔案。/etc/nginx 目錄中提供 mime.types 和 fastcgi_params 等檔案。

  • 未安裝部分 NGINX 模組，例如 nginx-plus-module-ndk。設定 $docroot 值，或在 NGINX 設定檔中手動新增值。

• 您可以視需要透過下列方式指定執行階段版本：

  • 在 app.yaml 中納入 runtime_version 設定。根據預設，如果未指定 runtime_version 設定，系統會使用最新的 PHP 版本。

    • 如要在 Ubuntu 22 上指定 PHP 8.4：

      runtime: php
      env: flex
      
      runtime_config:
          operating_system: "ubuntu22"
          runtime_version: "8.4"
          document_root: .
      

    • 如要在 Ubuntu 22 上指定支援的最新 PHP 版本，請按照下列步驟操作：

        runtime: php
        env: flex
      
        runtime_config:
            operating_system: "ubuntu22"
            document_root: .
      

  • 在 composer.json 檔案中加入 PHP 版本。

    {
        "require": {
            "php": "8.4.*"
        }
    }
    

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

先前的執行階段版本

如要使用 PHP 7.3 以下版本，您必須：

• 為應用程式宣告文件檔的根目錄。您可以在 app.yaml 檔案中執行這項操作：

  runtime: php
  env: flex
  api_version: 1
  
  runtime_config:
    document_root: .
  

  雖然您可以將專案根目錄 (.) 指定為文件根目錄，但建議您為 document_root 設定使用子目錄。

• 在 composer.json 檔案中指定 PHP 版本，以防止應用程式在新版本 PHP 推出時自動更新。

  {
      "require": {
          "php": "7.3.*"
      }
  }
  

支援其他 PHP 執行階段

如果您需要使用不受支援的 PHP 版本，可以建立自訂執行階段，並選取含有所需 PHP 版本的有效基礎映像檔。

如要瞭解 Google 提供的基本映像檔或 Docker PHP 基本映像檔，請參閱「建構自訂執行階段」一文。

自訂 NGINX

如要定義自訂設定檔，請在專案的根目錄中加入 nginx-app.conf 檔案。

根據預設，架構前端控制器會使用 index.php 檔案。您可能需要依據您的專案情況，進行些許修改。例如，Symfony 架構使用 app.php，而不是 index.php。您可以在 app.yaml 檔案的 runtime_config 區段中變更檔案名稱：

runtime: php
env: flex

runtime_config:
  operating_system: "ubuntu22"
  document_root: .
  front_controller_file: app.php

在 7.3 以下版本中，nginx-app.conf 設定檔會包含在主要 NGINX 設定檔的伺服器區段中。舉例來說，預設設定 php-app.conf 檔案包含以下內容：

location / {
# try to serve files directly, fallback to the front controller
try_files $uri /$front_controller_file$is_args$args;
}

如要定義自訂設定檔，請在專案的根目錄中建立 nginx-app.conf 檔案。執行階段會以您提供的檔案覆寫預設檔案。

根據預設，架構前端控制器會使用 index.php 檔案。您可能需要依據您的專案情況，進行些許修改。例如，Symfony 架構使用 app.php，而不是 index.php。您可以在 app.yaml 檔案的 runtime_config 區段中變更檔案名稱：

runtime: php
env: flex

runtime_config:
  document_root: .
  front_controller_file: app.php

OPcache

在 php.ini 檔案中啟用 OPcache。如要瞭解如何設定 OPcache，請參閱官方說明文件。

如要停用 OPcache，請在 php.ini 檔案中建立或編輯下列程式碼：

opcache.enable=0

依附元件

執行階段會在應用程式的來源目錄中尋找 composer.json 檔案，並在啟動應用程序前使用 composer 安裝任何依附元件。如要進一步瞭解如何宣告及管理套件，請參閱使用 PHP 程式庫一文。

使用 PHP 擴充功能

系統上會預載並啟用下列 PHP 擴充功能：

如要啟用擴充功能，請在應用程式的根目錄中新增 php.ini 檔案，並使用 extension 指令：

; Enable the Redis extension
extension=redis.so

; Enable the OpenTelemetry extension (must be in an opentelemetry section)
[opentelemetry]
extension=opentelemetry.so

此外，您也可以在 composer.json 中新增 require，即可啟用擴充功能：

{
    "require": {
        "ext-redis": "*"
    }
}

這些套件可讓您安裝最熱門的 PHP 擴充功能。如果您的應用程式需要其他的作業系統層級依附元件，您必須擴充 PHP 執行階段或使用自訂執行階段安裝合適的套件。

HTTPS 和轉送 Proxy

App Engine 會在負載平衡器上終止 HTTPS 連線，並將要求轉送至您的應用程式。當某項要求透過 HTTPS 傳送時，NGINX 伺服器的設定會將 HTTPS 環境變數 ($_SERVER["HTTPS"]) 設為 on。

部分應用程式還需確認使用者的 IP 位址，而這項資訊可在標準 X-Forwarded-For 標頭中取得。

停用的函式

當 php.ini 中含有 disable_functions 指令時，以下函數會遭到停用：

• exec
• passthru
• proc_open
• proc_close
• shell_exec
• show_source
• symlink
• system

如果您必須使用上述任一函式，請在應用程式的根目錄中新增 php.ini 檔案並變更 disable_functions 指令。此外，您也可以在 app.yaml 的 runtime_config 區段中，將 whitelist_functions 設定為以逗號為分隔的允許函式列表。

對於 PHP 7.3 以下版本，系統會安裝 suhosin Security 擴充功能，並預設在模擬模式中執行。模擬模式會記錄潛在危險函式的使用情況，並在 Cloud Logging UI 中顯示這些函式。如果關閉模擬模式，使用潛在危險函式時會導致您的應用程式結束。如要啟用這項額外的安全性功能，請在專案根目錄中新增 php.ini，程式碼如下：

; Prevent the use of potentially dangerous functions rather than logging them
suhosin.simulation = Off

修補函式

parse_str 是一種修補函式，您必須使用它的第二個參數。如果您只透過一個參數呼叫 parse_str，系統會發出警告，且不會呼叫函式。

可用的設定

您可以在 runtime_config 區段中加入下列設定：

您可以在 app.yaml 檔案的 build_env_variables 區段中設定 NGINX_SERVES_STATIC_FILES 環境變數，藉此控制 Nginx 是否為相符的 URI 提供靜態檔案：

runtime: php
env: flex

runtime_config:
  document_root: "web"
  operating_system: "ubuntu22"

build_env_variables:
  NGINX_SERVES_STATIC_FILES: true

在 PHP 執行階段中設定 supervisord

App Engine 彈性環境會使用 supervisord 來管理程序。根據預設，supervisord 會執行 nginx 和 php-fpm 來執行 PHP 網路應用程式；不過，部分應用程式仍需執行外部處理程序。此外，這類應用程式有時不需要 nginx 和 php-fpm。

如要新增由 supervisord 管理的程序，請將名為 additional-supervisord.conf 的檔案加到專案根目錄中。針對這個情況，以下內容提供設定檔範例：

[program:quote-updater]
command = php %(ENV_APP_DIR)s/worker.php
stdout_logfile = /dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile = /dev/stderr
stderr_logfile_maxbytes=0
user = www-data
autostart = true
autorestart = true
priority = 5
stopwaitsecs = 20

如要將 nginx 和 php-fpm 替換為程序，請在專案根目錄中新增一個名為 supervisord.conf 的檔案。針對這個情況，以下內容提供設定檔範例：

[supervisord]
nodaemon = true
logfile = /dev/null
logfile_maxbytes = 0
pidfile = /var/run/supervisord.pid

[program:react-server]
command = php %(ENV_APP_DIR)s/index.php
stdout_logfile = /dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile = /dev/stderr
stderr_logfile_maxbytes=0
user = www-data
autostart = true
autorestart = true
priority = 5
stopwaitsecs = 20

擴充執行階段

App Engine 彈性環境的 PHP 執行階段可用於建立自訂執行階段。詳情請參閱「自訂 PHP 執行階段」。

環境變數

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

您可以使用 app.yaml 設定其他環境變數。

中繼資料伺服器

您應用程式中的每個執行個體都可以使用 Compute Engine 中繼資料伺服器來查詢該執行個體的相關資訊，包括主機名稱、外部 IP 位址、執行個體 ID、自訂中繼資料，以及服務帳戶資訊。雖然 App Engine 不允許您為每個執行個體設定自訂中繼資料，但是您可以設定全專案的自訂中繼資料，並從 App Engine 和 Compute Engine 執行個體讀取該中繼資料。

這個函式範例使用中繼資料伺服器，以取得執行個體的外部 IP 位址：

function get_external_ip_using_google_cloud()
{
    $metadata = new Google\Cloud\Core\Compute\Metadata();
    $externalIp = $metadata->get(
        'instance/network-interfaces/0/access-configs/0/external-ip');

    return $externalIp;
}

function get_external_ip_using_curl()
{
    $url = 'http://metadata.google.internal/computeMetadata/v1/' .
        'instance/network-interfaces/0/access-configs/0/external-ip';

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