本頁面由 Cloud Translation API 翻譯而成。

PHP 執行階段

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

PHP 版本

PHP 8.4 使用建構套件。如需支援的完整 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 複製。mime.types 和 fastcgi_params 等檔案位於 /etc/nginx 目錄中。
- 部分 NGINX 模組 (例如 nginx-plus-module-ndk) 未安裝。設定 $docroot 值，或在 NGINX 設定檔中手動新增值。
您可以視需要透過下列方式指定執行階段版本：
- 包括 runtime_version 設定。app.yaml如未指定 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.*"
    }
}
```
  使用 MAJOR、MINOR 和 PATCH 指定 PHP 版本時，請將 PATCH 換成 *。請使用 MAJOR.MINOR.* 格式。 PHP 執行階段會定期更新至最新版本，並且一次只會支援一個版本，因此若您指定後續發行版本，可能會導致錯誤。
詳情請參閱 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.*"
    }
}
```
使用 MAJOR、MINOR 和 PATCH 指定 PHP 版本時，請將 PATCH 替換為 `*`。使用 MAJOR.MINOR.* 格式。PHP 執行階段會定期更新至最新版本，並且一次只會支援一個版本，因此若您指定後續發行版本，可能會導致錯誤。

支援其他 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 檔案。執行階段會以您提供的檔案覆寫預設檔案。

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 版本

您可以使用 php.ini 檔案啟用下列擴充功能：

7.3 以下版本

下列 PHP 擴充功能預設為停用。您可以使用 php.ini 檔案啟用下列擴充功能：

amqp
APM (7.0+)
BCMath
Bitset
日曆
Cassandra
couchbase (7.0+)
ds (7.0+)
eio
ev
event
Exif
FTP
GD (支援 PNG, JPEG 和 FreeType)
gettext
gRPC
hprose
igbinary
intl
ImageMagick
jsond
krb5
lua (7.0+)
LZF
memprof
mongodb
MySQL (5.6)
oauth
OpenCensus
PCNTL
Phalcon (5.6、7.0)
pq
protobuf
rdkafka
Redis
SeasLog
Shmop
SOAP
SQLite3
SQLite (PDO)
stomp
swoole
sync
tcpwrap
timezonedb
v8js (7.0+)
vips (7.0+)
XMLRPC
XSL
yaconf (7.0+)
yaf
yaml

如要啟用擴充功能，請在應用程式的根目錄中新增 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 區段中加入下列設定：

名稱	說明	預設值
`document_root`	指定 nginx 和 PHP 的 `DOCUMENT_ROOT`。您必須使用專案根目錄的相對路徑。	必填欄位
`composer_flags`	您可以使用這個鍵覆寫部分組合器旗標。	`--no-dev --prefer-dist`
`enable_stackdriver_integration`	僅支援7.3 以下版本。如設為 true，執行階段會自動啟用 Google Cloud Observability 整合功能。這項設定需要 `google/cloud` 套件 v0.33 以上版本。	false
`skip_lockdown_document_root`	僅支援7.3 以下版本。根據預設，執行階段會對 `document_root` 目錄下的所有檔案和目錄設定嚴格的唯讀權限。如果設為 `true`，執行階段會略過權限變更。	false
`whitelist_functions`	僅支援7.3 以下版本。以半形逗號分隔的允許清單函式名稱。	空字串
`front_controller_file`	目錄存取的預設 PHP 檔案名稱。	`index.php`
`nginx_conf_http_include`	部分 nginx 設定的檔案名稱，會包含在主要 nginx 設定檔的 `http` 區段中。	`nginx-http.conf`
`nginx_conf_include`	部分 nginx 設定的檔案名稱，會包含在主要 nginx 設定檔的 `server` 區段中。	`nginx-app.conf`
`nginx_conf_override`	使用者提供的 nginx 設定檔名稱，將做為 nginx 主要設定檔。	`nginx.conf`
`php_fpm_conf_override`	使用者提供的 php-fpm 設定檔名稱，會包含在 `[app]` 區段底部，以便覆寫現有設定。	`php-fpm.conf`
`php_ini_override`	使用者提供的 PHP 設定檔名稱。	`php.ini`
`supervisord_conf_addition`	使用者提供的 supervisord 設定檔名稱，會包含在主要的 supervisord 設定檔中。	`additional-supervisord.conf`
`supervisord_conf_override`	使用者提供的 supervisord 設定檔名稱，會覆寫主要的 supervisord 設定檔。	`supervisord.conf`

您可以在 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 執行階段」。

環境變數

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

環境變數	說明
`GAE_INSTANCE`	目前執行個體的名稱。
`GAE_MEMORY_MB`	應用程式程序可用的記憶體量。
`GAE_SERVICE`	應用程式的 `app.yaml` 檔案中指定的服務名稱；如果未指定服務名稱，則設為 `default`。
`GAE_VERSION`	目前應用程式的版本標籤。
`GOOGLE_CLOUD_PROJECT`	與應用程式相關聯的專案 ID，會在 Google Cloud 控制台上顯示。
`PORT`	接收 HTTP 要求的通訊埠。

您可以使用 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);
}