O ambiente de execução do PHP

O ambiente de execução do PHP é a pilha de software responsável por instalar o código e as dependências do aplicativo e executá-lo no ambiente flexível.

Versões do PHP

O PHP 8.3 usa buildpacks. Para ver a lista completa de versões do PHP compatíveis e a versão correspondente do Ubuntu, consulte a Programação do suporte ao ambiente de execução.

Para usar uma versão compatível do PHP:

  • Instale o gcloud CLI versão 420.0.0 ou posterior. É possível atualizar as ferramentas da CLI executando o comando gcloud components update. Para conferir a versão instalada, execute o comando gcloud version.

  • Inclua as configurações runtime_config e operating_system no arquivo app.yaml para especificar um sistema operacional.

  • Declare a raiz do documento para o aplicativo no arquivo app.yaml:

      runtime: php
  env: flex

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

    Embora seja possível especificar o diretório raiz do projeto (.) como raiz do documento, recomendamos usar um subdiretório para a configuração document_root.

    O código-fonte está no diretório /workspace, em vez de no diretório raiz (/). Se você substituir qualquer configuração, os processos NGINX ou supervisor farão referência ao arquivo de configuração nesse diretório. Para atualizar as referências correspondentes, você deve fazer o seguinte:

    • Atualize todas as instruções include na configuração do NGINX para serem relativas a /workspace em vez de /etc/nginx.

    • Alguns arquivos, como gzip_params, não estão incluídos. Para referenciar esses arquivos, inclua o seu próprio ou copie um do GitHub. Arquivos como mime.types e fastcgi_params estão disponíveis no diretório /etc/nginx.

    • Alguns módulos do NGINX, como nginx-plus-module-ndk, não estão instalados. Defina o valor $docroot ou adicione-o manualmente ao arquivo de configuração NGINX.

  • Se preferir, especifique uma versão do ambiente de execução da seguinte maneira:

    • Incluindo a configuração runtime_version em app.yaml. Por padrão, a versão mais recente do PHP será usada se a configuração runtime_version não for especificada.

      • Para especificar o PHP 8.3 no Ubuntu 22:

        runtime: php
env: flex

runtime_config:
    operating_system: "ubuntu22"
    runtime_version: "8.3"
    document_root: .

      • Para especificar a versão mais recente compatível do PHP no Ubuntu 22:

          runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: .

    • Como incluir uma versão do PHP no arquivo composer.json.

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

    Consulte a referência app.yaml para mais informações.

Versões anteriores do ambiente de execução

Para a versão 7.3 e anteriores do PHP:

  • Declare a raiz do documento do aplicativo. Você pode fazer isso no arquivo app.yaml:

    runtime: php
env: flex
api_version: 1

runtime_config:
  document_root: .

    Embora seja possível especificar o diretório raiz do projeto (.) como raiz do documento, recomendamos usar um subdiretório para a configuração document_root.

  • Especifique uma versão do PHP no arquivo composer.json para evitar que o aplicativo seja atualizado automaticamente quando uma nova versão do PHP estiver disponível.

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

Compatibilidade com outros ambientes de execução do PHP

Se você precisa usar uma versão do PHP que não é compatível, crie um ambiente de execução personalizado e selecione uma imagem de base válida com a versão do PHP que você precisa.

Para imagens de base fornecidas pelo Google ou imagens de base do Docker PHP, consulte Como criar ambientes de execução personalizados.

Personalizar o NGINX

Para definir um arquivo de configuração personalizado, inclua o arquivo nginx-app.conf no diretório raiz do projeto.

Por padrão, o controlador frontal do framework usa o arquivo index.php. Talvez seja necessário mudar essa configuração no seu projeto. Por exemplo, o framework Symfony usa app.php em vez de index.php. É possível alterar o nome do arquivo na seção runtime_config do arquivo app.yaml:

runtime: php
env: flex

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

Para a versão 7.3 e anteriores, o arquivo de configuração nginx-app.conf é incluído na seção do servidor do arquivo de configuração NGINX principal. Por exemplo, o arquivo de configuração padrão php-app.conf contém o seguinte:

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

Para definir um arquivo de configuração personalizado, crie o arquivo nginx-app.conf no diretório raiz do projeto. O ambiente de execução substitui o arquivo padrão pelo arquivo fornecido.

Por padrão, o controlador frontal do framework usa o arquivo index.php. Talvez seja necessário mudar essa configuração no seu projeto. Por exemplo, o framework Symfony usa app.php em vez de index.php. É possível alterar o nome do arquivo na seção runtime_config do arquivo app.yaml:

runtime: php
env: flex

runtime_config:
  document_root: .
  front_controller_file: app.php

OPcache

Ative o OPcache no arquivo php.ini. Consulte o documento oficial sobre como configurar o OPcache.

Para desativar o OPcache, crie ou edite o arquivo php.ini com a seguinte linha:

opcache.enable=0

Dependências

O ambiente de execução procura um arquivo composer.json no diretório de origem do aplicativo e usa o composer (ambos em inglês) para instalar as dependências antes de iniciar o aplicativo. Para mais informações sobre como declarar e gerenciar pacotes, consulte Como usar bibliotecas do PHP.

Como usar as extensões do PHP

As extensões do PHP a seguir estão pré-instaladas e ativadas no sistema:

Versões do PHP compatíveis

É possível ativar as seguintes extensões usando o arquivo php.ini:

v7.3 e anteriores

As extensões do PHP a seguir estão desativadas por padrão. É possível ativar as seguintes extensões usando o arquivo php.ini:

Para ativar uma extensão, adicione um arquivo php.ini na raiz do aplicativo com a diretiva extension:

; Enable the Redis extension
extension=redis.so

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

Como alternativa, também é possível ativar uma extensão adicionando require ao seu composer.json:

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

Esses pacotes permitem a instalação das extensões do PHP mais usadas. Se o aplicativo exigir outras dependências no nível do sistema operacional, será necessário estender o ambiente de execução do PHP ou usar um ambiente de execução personalizado para instalar os pacotes adequados.

HTTPS e proxies de encaminhamento

O App Engine encerra a conexão HTTPS no balanceador de carga e encaminha a solicitação ao aplicativo. Quando a solicitação é feita via HTTPS, o servidor NGINX é configurado para definir a variável de ambiente HTTPS ($_SERVER["HTTPS"]) para on.

Alguns aplicativos também precisam averiguar o endereço IP do usuário. Isso está disponível no cabeçalho X-Forwarded-For padrão.

Funções desativadas

As seguintes funções estão desativadas com a diretiva disable_functions em php.ini:

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

Se você precisar de qualquer uma das funções acima, adicione um arquivo php.ini na raiz do seu aplicativo e altere a diretiva disable_functions. Como alternativa, defina whitelist_functions na seção runtime_config em app.yaml para uma lista delimitada por vírgulas de funções para permitir.

Para o PHP versão 7.3 e versões anteriores, a extensão de segurança suhosin está instalada e configurada por padrão para ser executada no modo de simulação. O modo de simulação registra o uso de funções potencialmente perigosas, que serão mostradas na interface do Cloud Logging. Desativar o modo de simulação resultará no encerramento do aplicativo quando uma função potencialmente perigosa for usada. Para ativar esse recurso extra de segurança, adicione um php.ini na raiz do seu projeto com a seguinte opção:

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

Funções que receberam patch

A função parse_str recebeu patch, e o segundo parâmetro é obrigatório. Se você chamar parse_str com apenas um parâmetro, ele acionará um aviso e a função não será chamada.

Configurações disponíveis

É possível incluir as seguintes configurações na seção runtime_config:

NomeDescriçãoValor padrão
document_root Especifica DOCUMENT_ROOT para nginx e PHP. É necessário usar um caminho relativo do diretório raiz do projeto. Campo obrigatório
composer_flags Você pode modificar alguns sinalizadores de composição com essa chave. --no-dev --prefer-dist
enable_stackdriver_integration Compatível apenas com a versão 7.3 e versões anteriores. Quando definida como "true", o ambiente de execução ativa automaticamente a integração de observabilidade do Google Cloud. Essa configuração requer o pacote google/cloud v0.33 ou mais recente. falso
skip_lockdown_document_root Compatível apenas com a versão 7.3 e versões anteriores. Por padrão, o ambiente de execução definirá uma permissão estrita e somente leitura em todos os arquivos e diretórios no diretório document_root. Quando definido como true, o ambiente de execução ignora a alteração da permissão. falso
whitelist_functions Compatível apenas com a versão 7.3 e versões anteriores. Uma lista separada por vírgulas de nomes de funções para colocar na lista de permissões. Uma string vazia
front_controller_file Nome do arquivo PHP padrão para acesso ao diretório. index.php
nginx_conf_http_include Nome do arquivo de configuração parcial nginx, que será incluído na seção http do arquivo de configuração nginx principal. nginx-http.conf
nginx_conf_include Nome do arquivo de configuração parcial nginx, que será incluído na seção serverhttp do arquivo de configuração nginx principal. nginx-app.conf
nginx_conf_override Nome do arquivo de configuração nginx fornecido pelo usuário, que será usado como o arquivo de configuração nginx principal. nginx.conf
php_fpm_conf_override Nome do arquivo de configuração php-fpm fornecido pelo usuário, que será incluído na parte inferior da seção [app] para modificar as configurações existentes. php-fpm.conf
php_ini_override Nome do arquivo de configuração PHP fornecido pelo usuário. php.ini
supervisord_conf_addition Nome do arquivo de configuração supervisord fornecido pelo usuário, que será incluído no arquivo de configuração supervisord principal. additional-supervisord.conf
supervisord_conf_override Nome do arquivo de configuração supervisord fornecido pelo usuário, que modificará o arquivo de configuração supervisord principal. supervisord.conf

É possível controlar se o Nginx serve arquivos estáticos para URIs correspondentes definindo a variável de ambiente NGINX_SERVES_STATIC_FILES na seção build_env_variables do arquivo app.yaml:

runtime: php
env: flex

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

build_env_variables:
  NGINX_SERVES_STATIC_FILES: true

Como configurar o supervisord no tempo de execução do PHP

O ambiente flexível do App Engine usa o supervisord para gerenciar processos. Por padrão, supervisord executa nginx e php-fpm para executar aplicativos da Web PHP. No entanto, alguns aplicativos precisam executar processos externos. Além disso, esses aplicativos nem sempre precisam de nginx ou php-fpm.

Para adicionar um processo gerenciado por supervisord, adicione um arquivo chamado additional-supervisord.conf ao diretório raiz do projeto. Veja a seguir um conteúdo de arquivo de configuração de exemplo para este caso:

[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

Para substituir nginx e php-fpm pelo seu processo, adicione um arquivo chamado supervisord.conf ao diretório raiz do projeto. Veja a seguir um conteúdo de arquivo de configuração de exemplo para este caso:

[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

Como ampliar o tempo de execução

O ambiente de execução PHP do ambiente flexível do App Engine pode ser usado para criar um ambiente de execução personalizado. Para mais informações, consulte Como personalizar o ambiente de execução do PHP.

Variáveis de ambiente

As variáveis de ambiente a seguir são definidas pelo ambiente do ambiente de execução:

Variável de ambiente Descrição
GAE_INSTANCE O nome da instância atual.
GAE_MEMORY_MB A quantidade de memória disponível para o processo do aplicativo.
GAE_SERVICE O nome do serviço especificado no arquivo app.yaml do aplicativo. Se nenhum nome de serviço for especificado, será definido como default.
GAE_VERSION O rótulo da versão do aplicativo atual.
GOOGLE_CLOUD_PROJECT O ID do projeto associado ao seu aplicativo, que fica visível no console do Google Cloud
PORT A porta que receberá as solicitações HTTP.

Para definir variáveis extras de ambiente, use app.yaml.

Servidor de metadados

Cada instância do aplicativo pode usar o servidor de metadados do Compute Engine para consultar informações sobre a instância, incluindo o nome do host, o endereço IP externo, o código da instância, metadados personalizados e informações sobre a conta do serviço. Não é possível definir metadados personalizados para cada instância no App Engine. Em vez disso, defina metadados personalizados para o projeto e leia esses metadados a partir das instâncias do App Engine e do Compute Engine.

A função de exemplo abaixo usa o servidor de metadados para receber o endereço IP externo de uma instância:

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);
}