PHP 运行时

PHP 运行时是负责安装应用代码和依赖项,然后在柔性环境中运行该应用的软件栈。

PHP 版本

PHP 8.3 使用 buildpack。如需查看受支持的 PHP 版本及其对应 Ubuntu 版本的完整列表,请参阅运行时支持时间表

如需使用受支持的 PHP 版本,您必须:

  • 安装 gcloud CLI 420.0.0 版或更高版本。您可以通过运行 gcloud components update 命令来更新 CLI 工具。如需查看已安装的版本,您可以运行 gcloud version 命令。

  • app.yaml 文件中添加 runtime_configoperating_system 设置以指定操作系统。

  • app.yaml 文件中声明应用的文档根目录:

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

    虽然您可以将项目根 (.) 目录指定为文档根目录,但建议您在 document_root 设置中使用子目录。

    源代码位于 /workspace 目录,而不是根目录 (/) 中。如果您替换了任何配置,则 NGINXsupervisor 进程会引用此目录中的配置文件。如需更新相应的引用,您必须满足以下条件:

    • 将 NGINX 配置中的任何 include 语句更新为相对于 /workspace,而不是 /etc/nginx

    • 不包含 gzip_params 等某些文件。如需引用这些文件,请添加您自己的文件或从 GitHub 中复制。mime.typesfastcgi_params 等文件位于 /etc/nginx 目录中。

    • 未安装 nginx-plus-module-ndk 等某些 NGINX 模块。设置 $docroot 值或在 NGINX 配置文件中手动添加该值。

  • (可选)您可以通过以下方式指定运行时版本:

    • app.yaml 中添加 runtime_version 设置。默认情况下,如果未指定 runtime_version 设置,则系统会使用最新的 PHP 版本。

      • 如需在 Ubuntu 22 上指定 PHP 8.3,请运行以下命令:

        runtime: php
        env: flex
        
        runtime_config:
            operating_system: "ubuntu22"
            runtime_version: "8.3"
            document_root: .
        
      • 如需在 Ubuntu 22 上指定受支持的最新 PHP 版本,请运行以下命令:

          runtime: php
          env: flex
        
          runtime_config:
              operating_system: "ubuntu22"
              document_root: .
        
    • composer.json 文件中添加 PHP 版本。

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

    如需了解详情,请参阅 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 版本

您可以使用 php.ini 文件启用以下扩展程序:

v7.3 及更低版本

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

如需启用扩展程序,请使用 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.yamlruntime_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

在 PHP 运行时中配置 supervisord

App Engine 柔性环境使用 supervisord 管理进程。默认情况下,supervisord 运行 nginxphp-fpm 来运行 PHP Web 应用;但是,某些应用需要运行外部进程。此外,此类应用有时甚至不需要 nginxphp-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

如果要将 nginxphp-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);
}