Ambiente de execução do PHP

O ambiente de execução do PHP é a pilha de software responsável por instalar o código do serviço da Web e respectivas dependências e executar o serviço.

Para especificar o PHP no ambiente padrão do App Engine, declare o ambiente de execução no arquivo app.yaml. Exemplo:

runtime: phpVERSION

Em que VERSION são os números de versão MAJOR e MINOR do PHP. Por exemplo, para usar a versão mais recente do PHP, PHP 8.3, especifique 83.

Para outras versões compatíveis do PHP e a versão do Ubuntu correspondente à sua versão do PHP, consulte a Programação de suporte do ambiente de execução.

Versão do PHP

O ambiente de execução do PHP usa a versão estável mais recente da versão especificada no seu arquivo app.yaml. O App Engine é atualizado automaticamente com novas versões de lançamento de patch, mas isso não acontece com a versão secundária.

Por exemplo, seu app pode ser implantado no PHP 7.3.0 e depois atualizado automaticamente para a versão 7.3.1, mas não será atualizado automaticamente para o PHP 7.4.0.

Inicialização do app

Será necessário implantar um controlador frontal para lidar com todo o roteamento de solicitações.

Nos exemplos a seguir, confira maneiras diferentes de exibir seu app:

Se seu app contiver um arquivo public/index.php ou index.php, o App Engine usará esse arquivo para exibir o app.

Recomendamos usar um framework, como Laravel, Symfony ou Slim (em inglês), porque ele fornece roteamento leve para gravar e implantar apps PHP rapidamente. Confira um exemplo do controlador frontal Slim (em inglês).

No entanto, se você estiver migrando um app legado, consulte o seguinte arquivo index.php de exemplo para importar os arquivos PHP necessários e implementar o controlador frontal manualmente:
```
switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
    case '/':
        require 'homepage.php';
        break;
    case '/contact.php':
        require 'contact.php';
        break;
    default:
        http_response_code(404);
        exit('Not Found');
}
```
Se você especificar o elemento entrypoint opcional no arquivo app.yaml, o App Engine usará o comando no elemento entrypoint para exibir o app em vez de usar public/index.php ou index.php:
```
    entrypoint: serve path/to/my/front/controller.php
```
O campo entrypoint usa o comando serve integrado, que é um programa no ambiente de execução do PHP que inicia a implementação de php-fpm e um servidor da Web em segundo plano. Esse servidor da Web roteia todo o tráfego para o arquivo PHP fornecido usando o padrão de design do controlador frontal.

O comando serve tem duas sinalizações opcionais:
- --workers=N: especifica o número N de php-fpm workers. Se você não definir a sinalização --workers, o comando serve adivinhará o número de workers com base no volume de memória disponível. Para melhores resultados, defina o mesmo valor para a sinalização --workers no comando serve e no elemento max_concurrent_requests.
- --enable-dynamic-workers: especifica que você quer que os workers php-fpm sejam gerados somente conforme necessário. O padrão é usar uma política estática para os workers php-fpm. É possível alterar o número máximo de workers gerados usando a sinalização --workers=N. Por padrão, o número máximo de workers gerados é o definido pela política estática.
As sinalizações opcionais precisam vir antes do caminho do controlador frontal:
```
    entrypoint: serve --workers=2 --enable-dynamic-workers path/to/index.php
```
Para implantar um processo de worker de longa duração, defina o elemento entrypoint com o caminho de arquivo do processo do worker:
```
    entrypoint: php long-running-worker-file.php
```
Se o elemento entrypoint executar um script com um processo de longa duração, como um worker do Pub/Sub inscrito em um tópico, não use o comando serve.

Para mais informações, consulte a referência de app.yaml.

Extensões ativadas

As extensões a seguir foram ativadas no ambiente de execução do PHP para o App Engine:

BCMath
bz2
Calendar
core
cgi
ctype
cURL
date
dba
dom
enchant
Exif
fcgi
fileinfo
filter
FTP
GD
gettext
GMP
hash
iconv
intl
json
LDAP
libxml
mbstring
MYSQLi
mysqlnd
MySQL (PDO)
OPcache
OpenSSL
PCNTL
pcre
PDO
pgsql
Phar
posix
PostgreSQL (PDO)
Reflection
session
Shmop
SimpleXML
SOAP
Sockets
sodium (PHP 8.x only, not available for PHP 7.x)
SPL
SQLite (PDO)
SQLite3
standard
test
tidy
tokenizer
XML
XMLreader
XMLrpc (PHP 7.x only, not available for PHP 8.x)
XMLwriter
XSL
zend
Zip
Zlib

Extensões carregáveis dinamicamente

É possível carregar dinamicamente as extensões a seguir configurando php.ini:

Para ativar essas extensões, adicione as devidas diretivas ao arquivo php.ini em extension. Por exemplo:

extension=memcached.so
extension=grpc.so
extension=protobuf.so
extension=mongodb.so
extension=imagick.so
extension=opencensus.so
extension=redis.so

[opentelemetry]
extension=opentelemetry.so

Variáveis de ambiente

As seguintes variáveis de ambiente são definidas pelo ambiente de execução:

Variável de ambiente	Descrição
`GAE_APPLICATION`	O ID do aplicativo do App Engine. Esse ID tem o prefixo "`region code`~", como "e~" para aplicativos implantados na Europa.
`GAE_DEPLOYMENT_ID`	O ID da implantação atual.
`GAE_ENV`	O ambiente do App Engine. Defina como `standard`.
`GAE_INSTANCE`	O ID da instância em que o serviço é executado no momento.
`GAE_MEMORY_MB`	A quantidade de memória disponível para o processo do aplicativo em MB.
`GAE_RUNTIME`	O ambiente de execução especificado no seu arquivo `app.yaml`.
`GAE_SERVICE`	O nome do serviço especificado no seu arquivo `app.yaml`. Se nenhum nome de serviço for especificado, ele será definido como `default`.
`GAE_VERSION`	O rótulo da versão atual do serviço.
`GOOGLE_CLOUD_PROJECT`	O ID do projeto do Google Cloud associado ao aplicativo.
`PORT`	A porta que recebe solicitações HTTP.
`NODE_ENV` (disponível apenas no ambiente de execução do Node.js)	Definido como `production` quando o serviço for implantado.

É possível definir outras variáveis de ambiente no arquivo app.yaml, mas os valores acima não podem ser modificados, exceto para NODE_ENV.

HTTPS e proxies de encaminhamento

O App Engine encerra as conexões HTTPS no balanceador de carga e encaminha as solicitações para o aplicativo. Em alguns aplicativos, é necessário determinar o protocolo e o IP de solicitação originais. O endereço IP do usuário está disponível no cabeçalho X-Forwarded-For padrão. Os aplicativos que necessitam dessa informação precisam configurar a biblioteca da Web para confiar no proxy.

Sistema de arquivos

O ambiente de execução inclui um diretório /tmp gravável, e todos os outros diretórios têm acesso somente de leitura. A gravação em /tmp ocupa a memória do sistema. Para mais informações, consulte Compatibilidade de tempnam() e sys_get_temp_dir().

Servidor de metadados

Cada instância do aplicativo pode usar o servidor de metadados do App Engine para consultar informações sobre a instância e o projeto.

É possível acessar o servidor de metadados por meio dos endpoints a seguir:

http://metadata
http://metadata.google.internal

As solicitações enviadas ao servidor de metadados precisam incluir o cabeçalho da solicitação Metadata-Flavor: Google. Esse cabeçalho indica que a solicitação foi enviada para recuperar valores de metadados.

A tabela a seguir lista os endpoints em que é possível fazer solicitações HTTP para metadados específicos.

Endpoint de metadados	Descrição
`/computeMetadata/v1/project/numeric-project-id`	Número do projeto atribuído ao seu projeto.
`/computeMetadata/v1/project/project-id`	ID do projeto atribuído ao seu projeto.
`/computeMetadata/v1/instance/region`	A região em que a instância está em execução.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	E-mail da conta de serviço padrão atribuído ao seu projeto.
`/computeMetadata/v1/instance/service-accounts/default/`	Lista todas as contas de serviço padrão do seu projeto.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	Lista todos os escopos compatíveis com as contas de serviço padrão.
`/computeMetadata/v1/instance/service-accounts/default/token`	Retorna o token de autenticação que pode ser usado para autenticar o aplicativo em outras Google Cloud APIs.

Por exemplo, para recuperar o ID do projeto, envie uma solicitação para http://metadata.google.internal/computeMetadata/v1/project/project-id.

A seguir, confira um exemplo de como chamar os endpoints de metadados usando cURL ou a biblioteca de cliente do Google Cloud:

/**
 * Requests a key from the Metadata server using the Google Cloud SDK. Install
 * the Google Cloud SDK by running "composer install google/cloud"
 *
 * @param $metadataKey the key for the metadata server
 */
function request_metadata_using_google_cloud($metadataKey)
{
    $metadata = new Google\Cloud\Core\Compute\Metadata();
    $metadataValue = $metadata->get($metadataKey);

    return $metadataValue;
}

/**
 * Requests a key from the Metadata server using cURL.
 *
 * @param $metadataKey the key for the metadata server
 */
function request_metadata_using_curl($metadataKey)
{
    $url = 'http://metadata/computeMetadata/v1/' . $metadataKey;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Metadata-Flavor: Google'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    return curl_exec($ch);
}

Sessões

O PHP fornece uma camada de gerenciamento de sessão que permite que os apps da Web preservem as informações de estado do usuário entre solicitações. As sessões no App Engine funcionam de modo semelhante às sessões em qualquer outro app PHP.

Para definir uma variável na sessão de um usuário, use o código a seguir:

session_start();
$_SESSION['Foo'] = 'Bar';

O código a seguir imprimirá Bar em uma solicitação subsequente do mesmo usuário:

session_start();
print $_SESSION['Foo']; // prints Bar

Para sessões mais longas, use um serviço de armazenamento alternativo, como o Cloud SQL.

Chaves especiais de $_SERVER

O PHP disponibiliza a matriz especial $_SERVER[] no escopo da solicitação. Além dos parâmetros padrão de CGI, o App Engine adiciona outras chaves úteis:

GAE_APPLICATION: ID do projeto do Google Cloud do app atual.
GAE_DEPLOYMENT_ID: ID do código-fonte implantado.
GAE_ENV: o ambiente do App Engine (padrão ou flexível) em que o app é executado.
GAE_INSTANCE: nome da instância atualmente em execução.
GAE_MEMORY_MB: volume de memória disponível para o processo do app, em MB.
GAE_RUNTIME: o ambiente de execução especificado no arquivo app.yaml, como php72.
GAE_SERVICE: nome do serviço implantado atualmente.
GAE_VERSION: nome da versão implantada atualmente.
GOOGLE_CLOUD_PROJECT: ID do projeto do Google Cloud.
HTTP_X_APPENGINE_CITY: nome da cidade de origem da solicitação. Por exemplo, uma solicitação proveniente da cidade de Mountain View pode ter o valor de cabeçalho "mountain view".
HTTP_X_APPENGINE_CITYLATLONG: latitude e longitude da cidade que originou a solicitação. Essa string pode ser algo como "37.386051,-122.083851" para uma solicitação de Mountain View.
HTTP_X_APPENGINE_COUNTRY: país que originou a solicitação, como um código de país ISO 3166-1 alfa-2. O App Engine determina esse código pelo endereço IP do cliente.
HTTP_X_APPENGINE_HTTPS: verifica o uso de HTTPS.
HTTP_X_APPENGINE_REGION: nome da região de origem da solicitação. Esse valor só faz sentido no contexto do país em X-Appengine-Country. Por exemplo, se o país for "US" e a região for "ca", esse "ca" significará "Califórnia", não Canadá.
HTTP_X_APPENGINE_USER_IP: endereço IP do cliente. Observe que $_SERVER['HTTP_X_APPENGINE_USER_IP'] é a única maneira de o app recuperar o endereço IP do cliente. A variável $_SERVER['REMOTE_ADDR'] não está disponível no App Engine.

Diretivas com novos padrões de inicialização

A tabela a seguir especifica diretivas cujos padrões de inicialização diferem daqueles fornecidos com o interpretador PHP padrão disponível em php.net. Para encontrar os valores padrão para diretivas não especificadas na tabela a seguir: consulte as diretivas php.ini.

Diretiva	Valor padrão no App Engine
`expose_php`	`Off`
`memory_limit`	`-1`
`max_execution_time`	`0`
`error_reporting`	`E_ALL & ~E_DEPRECATED & ~E_STRICT`
`display_errors`	`Off`
`display_startup_errors`	`Off`
`log_errors`	`On`
`log_errors_max_len`	`0`
`ignore_repeated_errors`	`Off`
`ignore_repeated_source`	`Off`
`html_errors`	`Off`
`opcache.enable`	`On`
`opcache.validate_timestamps`	`Off`
`opcache.memory_consumption`	`32`

Substitua essas diretivas padrão incluindo-as em um arquivo php.ini de seu app.

Compatibilidade de `tempnam()` e `sys_get_temp_dir()`

Os apps do App Engine são executados em um sandbox de segurança, em que apenas o diretório /tmp é gravável e armazenado na RAM da instância. Por esse motivo, a versão do App Engine de tempnam() (em inglês) retorna um arquivo temporário na memória que pode ser gravado em uma solução de armazenamento permanente, como buckets do Cloud Storage.

Confira um exemplo de como gravar no arquivo temporário na memória usando file_put_contents() e fwrite().

<?php
$dir = sys_get_temp_dir();
$tmp = tempnam($dir, "foo");
file_put_contents($tmp, "hello");
$f = fopen($tmp, "a");
fwrite($f, " world");
fclose($f);
echo file_get_contents($tmp);

A saída esperada do exemplo seria:

hello world

Como gerenciar dependências com o Composer

Para mais informações, consulte a página Como especificar dependências.