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 复制文件。mime.types 和 fastcgi_params 等文件位于 /etc/nginx 目录中。
- 未安装 nginx-plus-module-ndk 等某些 NGINX 模块。在 NGINX 配置文件中设置 $docroot 值或手动添加该值。
（可选）您可以通过以下方式指定运行时版本：
- 在 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.*"
    }
}
```
  使用 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 文件启用以下扩展程序：

v7.3 及更低版本

以下 PHP 扩展程序默认处于停用状态。您可以使用 php.ini 文件启用以下扩展程序：

amqp
APM（7.0 及更高版本）
BCMath
Bitset
日历
Cassandra
couchbase（7.0 及更高版本）
ds（7.0 及更高版本）
eio
ev
事件
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

如需启用扩展程序，请在应用的根目录中添加包含 extension 指令的 php.ini 文件：

; 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 和转发代理

App Engine 在负载均衡器上终止 HTTPS 连接，并将请求转发给应用。NGINX 服务器配置为在通过 HTTPS 发出请求时将 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 安全扩展程序，并将其配置为在模拟模式下运行。模拟模式会记录可能存在风险的函数使用情况，这些函数将显示在 Cloud Logging 界面中。关闭模拟模式将使应用在使用可能存在风险的函数时退出。如需启用这项附加安全功能，请使用以下选项在项目根目录中添加 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`	您可以使用此键替换某些 composer 标志。	`--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 Web 应用；但是，某些应用需要运行外部进程。另外，此类应用有时甚至不需要 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);
}