O tempo de execução do PHP

O tempo de execução do PHP é a pilha de software responsável por instalar o código da aplicação e as dependências e, em seguida, executar essa aplicação no ambiente flexível.

Versões do PHP

O PHP 8.4 usa buildpacks. Para ver a lista completa das versões do PHP suportadas e a respetiva versão do Ubuntu, consulte a Programação de suporte de tempo de execução.

Para usar uma versão do PHP suportada, tem de:

  • Instale a versão gcloud CLI 420.0.0 ou posterior. Pode atualizar as ferramentas de CLI executando o comando gcloud components update. Para ver a versão instalada, pode executar o comando gcloud version.

  • Inclua as definições runtime_config e operating_system no ficheiro app.yaml para especificar um sistema operativo.

  • Declare a raiz do documento para a sua aplicação no ficheiro app.yaml:

      runtime: php
  env: flex

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

    Embora possa especificar o diretório raiz do projeto (.) como a raiz do documento, recomendamos que use um subdiretório para a definição document_root.

    O código-fonte está localizado no diretório /workspace em vez do diretório raiz (/). Se substituir alguma configuração, os processos NGINX ou supervisor referenciam o ficheiro de configuração neste diretório. Para atualizar as referências correspondentes, tem de:

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

    • Alguns ficheiros, como gzip_params, não estão incluídos. Para fazer referência a estes ficheiros, inclua os seus próprios ficheiros ou copie-os do GitHub. Os ficheiros, 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 de $docroot ou adicione o valor manualmente no ficheiro de configuração NGINX.

  • Opcionalmente, pode especificar uma versão do tempo de execução:

    • Incluindo a definição runtime_version no seu app.yaml. Por predefinição, é usada a versão mais recente do PHP se a definição runtime_version não for especificada.

      • Para especificar o PHP 8.4 no Ubuntu 22:

        runtime: php
env: flex

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

      • Para especificar a versão do PHP mais recente suportada no Ubuntu 22:

          runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: .

    • Incluindo uma versão PHP no ficheiro composer.json.

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

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

Versões de tempo de execução anteriores

Para usar o PHP versão 7.3 e anterior, tem de:

  • Declare a raiz do documento para a sua aplicação. Pode fazê-lo no ficheiro app.yaml:

    runtime: php
env: flex
api_version: 1

runtime_config:
  document_root: .

    Embora possa especificar o diretório raiz do projeto (.) como a raiz do documento, recomendamos que use um subdiretório para a definição document_root.

  • Especifique uma versão do PHP no ficheiro composer.json para impedir que a sua aplicação seja atualizada automaticamente quando estiver disponível uma nova versão do PHP.

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

Suporte de outros tempos de execução do PHP

Se precisar de usar uma versão do PHP que não seja suportada, pode criar um tempo de execução personalizado e selecionar uma imagem base válida com a versão do PHP de que precisa.

Para imagens base fornecidas pela Google ou imagens base do Docker PHP, consulte o artigo Criar tempos de execução personalizados.

Personalize o NGINX

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

Por predefinição, o controlador frontal da framework usa o ficheiro index.php. Pode ter de alterar esta definição para algo diferente para o seu projeto. Por exemplo, a framework Symfony usa app.php em vez de index.php. Pode alterar o nome do ficheiro na secção runtime_config do ficheiro 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 ficheiro de configuração nginx-app.conf está incluído na secção do servidor do ficheiro de configuração NGINX principal. Por exemplo, o ficheiro de configuração predefinida 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 ficheiro de configuração personalizado, crie o ficheiro nginx-app.conf no diretório raiz do seu projeto. O tempo de execução substitui o ficheiro predefinido pelo ficheiro que fornecer.

Por predefinição, o controlador frontal da framework usa o ficheiro index.php. Pode ter de alterar esta definição para algo diferente para o seu projeto. Por exemplo, a framework Symfony usa app.php em vez de index.php. Pode alterar o nome do ficheiro na secção runtime_config do ficheiro app.yaml:

runtime: php
env: flex

runtime_config:
  document_root: .
  front_controller_file: app.php

OPcache

Ative o OPcache no seu ficheiro php.ini. Consulte o documento oficial para saber como configurar o OPcache.

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

opcache.enable=0

Dependências

O tempo de execução procura um ficheiro composer.json no diretório de origem da sua aplicação e usa composer para instalar quaisquer dependências antes de iniciar a aplicação. Para mais informações sobre como declarar e gerir pacotes, consulte o artigo Usar bibliotecas PHP.

Usar extensões PHP

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

Versões do PHP compatíveis

Pode ativar as seguintes extensões através do ficheiro php.ini:

v7.3 e anteriores

As seguintes extensões PHP estão desativadas por predefinição. Pode ativar as seguintes extensões no ficheiro php.ini:

Para ativar uma extensão, adicione um ficheiro php.ini na raiz da sua aplicação 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

Em alternativa, também pode ativar uma extensão adicionando um require ao seu composer.json:

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

Estes pacotes permitem a instalação das extensões PHP mais populares. Se a sua aplicação exigir dependências adicionais ao nível do sistema operativo, tem de estender o tempo de execução do PHP ou usar um tempo de execução personalizado para instalar os pacotes adequados.

HTTPS e proxies de encaminhamento

O App Engine termina a ligação HTTPS no balanceador de carga e encaminha o pedido para a sua aplicação. O servidor NGINX está configurado para definir a variável de ambiente HTTPS ($_SERVER["HTTPS"]) como on quando o pedido é feito através de HTTPS.

Algumas aplicações também precisam de determinar o endereço IP do utilizador. Esta opção 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 precisar de alguma das funções acima, adicione um ficheiro php.ini na raiz da sua aplicação e altere a diretiva disable_functions. Em alternativa, defina whitelist_functions na secção runtime_config em app.yaml como uma lista de funções separadas por vírgulas a permitir.

Para a versão 7.3 e anteriores do PHP, a extensão de segurança suhosin é instalada e configurada por predefinição para ser executada no modo de simulação. O modo de simulação regista a utilização de funções potencialmente perigosas, que são apresentadas na IU do Cloud Logging. A desativação do modo de simulação faz com que a sua aplicação seja fechada quando é usada uma função potencialmente perigosa. Para ativar esta funcionalidade de segurança adicional, adicione um php.ini na raiz do projeto com a seguinte opção:

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

Funções corrigidas

A função parse_str foi corrigida e o segundo parâmetro é obrigatório. Se chamar parse_str com apenas um parâmetro, é apresentado um aviso e a função não é chamada.

Configurações disponíveis

Pode incluir as seguintes configurações na secção runtime_config:

NomeDescriçãoValor predefinido
document_root Especifica DOCUMENT_ROOT para o nginx e o PHP. Tem de usar um caminho relativo a partir do diretório raiz do projeto. Campo obrigatório
composer_flags Pode substituir algumas das flags do compositor com esta chave. --no-dev --prefer-dist
enable_stackdriver_integration Suportado apenas para a versão 7.3 e anteriores. Quando está definida como verdadeira, o tempo de execução ativa automaticamente a integração do Google Cloud Observability. Esta configuração requer o pacote google/cloud v0.33 ou superior. falso
skip_lockdown_document_root Suportado apenas para a versão 7.3 e anteriores. Por predefinição, o tempo de execução define uma autorização de leitura restrita em todos os ficheiros e diretórios na pasta document_root. Quando definida como true, o tempo de execução ignora a alteração da autorização. falso
whitelist_functions Suportado apenas para a versão 7.3 e anteriores. Uma lista de nomes de funções separados por vírgulas para permitir. Uma string vazia
front_controller_file Nome do ficheiro PHP predefinido para o acesso ao diretório. index.php
nginx_conf_http_include Nome de ficheiro de uma configuração parcial do nginx, que será incluída na secção http no ficheiro de configuração principal do nginx. nginx-http.conf
nginx_conf_include Nome de ficheiro de uma configuração parcial do nginx que será incluída na secção server no ficheiro de configuração principal do nginx. nginx-app.conf
nginx_conf_override Nome do ficheiro de um ficheiro de configuração do nginx fornecido pelo utilizador, que vai ser usado como o ficheiro de configuração principal do nginx. nginx.conf
php_fpm_conf_override Nome do ficheiro de um ficheiro de configuração php-fpm fornecido pelo utilizador, que será incluído na parte inferior da secção [app] para que substitua as configurações existentes. php-fpm.conf
php_ini_override Nome do ficheiro de um ficheiro de configuração PHP fornecido pelo utilizador. php.ini
supervisord_conf_addition Nome de ficheiro de um ficheiro de configuração do supervisord fornecido pelo utilizador, que será incluído no ficheiro de configuração do supervisord principal. additional-supervisord.conf
supervisord_conf_override Nome de ficheiro de um ficheiro de configuração do supervisord fornecido pelo utilizador, que substitui o ficheiro de configuração do supervisord principal. supervisord.conf

Pode controlar se o Nginx serve ficheiros estáticos para URIs correspondentes definindo a variável de ambiente NGINX_SERVES_STATIC_FILES na secção build_env_variables do ficheiro app.yaml:

runtime: php
env: flex

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

build_env_variables:
  NGINX_SERVES_STATIC_FILES: true

Configurar o supervisord no tempo de execução do PHP

O ambiente flexível do App Engine usa o supervisord para gerir processos. Por predefinição, o supervisord executa o nginx e o php-fpm para executar aplicações Web PHP. No entanto, algumas aplicações têm de executar processos externos. Além disso, por vezes, estas aplicações nem sequer precisam de nginx nem de php-fpm.

Se quiser adicionar um processo gerido pelo supervisord, adicione um ficheiro com o nome additional-supervisord.conf ao diretório raiz do projeto. Segue-se um exemplo do conteúdo do ficheiro de configuração 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

Se quiser substituir nginx e php-fpm pelo seu processo, adicione um ficheiro com o nome supervisord.conf ao diretório raiz do projeto. Segue-se um exemplo do conteúdo do ficheiro de configuração 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

Prolongar o tempo de funcionamento

O tempo de execução do PHP do ambiente flexível do App Engine pode ser usado para criar um tempo de execução personalizado. Consulte o artigo Personalizar o tempo de execução do PHP para mais informações.

Variáveis de ambiente

As seguintes variáveis de ambiente são definidas pelo ambiente de tempo 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 da aplicação.
GAE_SERVICE O nome do serviço especificado no ficheiro app.yaml da sua aplicação ou, se não for especificado nenhum nome do serviço, é definido como default.
GAE_VERSION A etiqueta da versão da aplicação atual.
GOOGLE_CLOUD_PROJECT O ID do projeto associado à sua aplicação, que é visível na Google Cloud consola
PORT A porta que vai receber pedidos HTTP.

Pode definir variáveis de ambiente adicionais com app.yaml.

Servidor de metadados

Cada instância da sua aplicação pode usar o servidor de metadados do Compute Engine para consultar informações sobre a instância, incluindo o respetivo nome do anfitrião, endereço IP externo, ID da instância, metadados personalizados e informações da conta de serviço. O App Engine não lhe permite definir metadados personalizados para cada instância, mas pode definir metadados personalizados ao nível do projeto e lê-los a partir das suas instâncias do App Engine e Compute Engine.

Esta função de exemplo usa o servidor de metadados para obter 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);
}