Ambiente de execução do PHP 5

Com o App Engine, você pode criar aplicativos da Web usando a linguagem de programação PHP. O aplicativo em PHP é executado na infraestrutura escalonável do Google e usa armazenamento permanente e serviços de larga escala.

Como selecionar o ambiente de execução do PHP

O App Engine executa o aplicativo da Web PHP usando um interpretador do PHP versão 5.5.34. Observação: no Linux, também é necessário instalar o PHP localmente para executar aplicativos em PHP.

Para configurar o aplicativo para usar o ambiente de execução do PHP, adicione o seguinte ao arquivo app.yaml:

runtime: php55
api_version: 1
...

O primeiro elemento, runtime, seleciona o ambiente de execução do PHP.

O segundo elemento, api_version, seleciona qual versão do ambiente de execução do PHP será usada. Quando este documento foi elaborado, o App Engine tinha apenas uma versão do ambiente do PHP, 1. Se houver alterações futuras que não sejam compatíveis com versões anteriores, a equipe do App Engine usará um novo identificador de versão. Seu aplicativo continuará usando a versão selecionada até que você altere a configuração da api_version e faça upload do aplicativo.

Para mais informações sobre o arquivo app.yaml e sobre como implantar o aplicativo no App Engine, consulte os tópicos Referência do app.yaml e Como implantar um aplicativo em PHP.

Sandbox

Para permitir que o App Engine distribua solicitações a aplicativos em vários servidores da Web e evitar que um aplicativo interfira no outro, o aplicativo é executado em um ambiente restrito de "sandbox". Nesse ambiente, o aplicativo pode executar código, usar o e-mail do App Engine, a busca de URL e serviços de usuários, além de examinar a solicitação da Web do usuário e preparar a resposta.

Um aplicativo do App Engine não pode:

  • gravar no sistema de arquivos. Os aplicativos em PHP podem usar o Google Cloud Storage para armazenar arquivos permanentes. É permitido ler o sistema de arquivos, e todos os arquivos enviados com o aplicativo estão disponíveis;

  • demorar para responder. Uma solicitação da Web para um aplicativo precisa ser processada em poucos segundos. Os processos que levam muito tempo para responder são encerrados para evitar sobrecarregar o servidor da Web;

  • fazer outros tipos de chamadas do sistema.

Carregamento automático de classes

As classes da Biblioteca PHP padrão (SPL, na sigla em inglês) e todas as classes que fazem parte do SDK do App Engine são carregadas automaticamente quando necessário. Isso significa que não é necessário usar instruções include ou require nos scripts PHP.

Por padrão, o carregamento de classes automático ocorrerá apenas para classes definidas em arquivos que residam no diretório raiz do SDK da raiz do App Engine (e para sua instalação local do PHP, se especificado por --php_executable_path).

Para adicionar mais caminhos a serem pesquisados para o carregamento de classes automático, use set_include_path no script PHP.

set_include_path('my_additional_path' . PATH_SEPARATOR . get_include_path());

Extensões ativadas

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

  • apc
  • bcmath
  • agenda
  • Principal
  • ctype
  • data
  • dom
  • ereg
  • exif
  • filtro
  • ftp
  • gd
  • hash
  • iconv
  • json
  • libxml
  • mailparse
  • mbstring
  • mcrypt
  • memcache
  • memcached
  • mysql
  • mysqli
  • mysqlnd
  • OAuth
  • openssl
  • pcre
  • PDO
  • pdo_mysql
  • Reflexo
  • sessão
  • shmop
  • SimpleXML
  • soap
  • sockets (para aplicativos com faturamento ativado)
  • SPL
  • padrão
  • tokenizer
  • xml
  • xmlreader
  • xmlwriter
  • xsl
  • zip
  • zlib

Extensões carregáveis dinamicamente

As extensões a seguir são dinamicamente carregáveis por meio da configuração de php.ini.

Para ativar essas extensões, adicione diretivas para elas no seu arquivo php.ini em extension da seguinte forma:

extension = "curl.so"
extension = "mongo.so"
extension = "imagick.so"
extension = "intl.so"
extension = "fileinfo.so"

Sessões

A maioria dos aplicativos da Web precisa preservar as informações de estado do usuário entre as solicitações. O PHP oferece uma prática camada de gerenciamento de sessão. As sessões no App Engine funcionam de modo semelhante às sessões em qualquer outro aplicativo PHP.

Definição de uma variável na sessão de um usuário:

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

Em uma solicitação subsequente pelo mesmo usuário:

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

Por padrão, o ambiente de execução do App Engine usa o Memcache para armazenar informações da sessão usando a classe MemcacheSessionHandler. É possível ajustar esse comportamento especificando seu próprio manipulador de sessões usando o método session_set_save_handler() do PHP. O Memcache permite que os dados da sessão sejam salvos e recuperados rapidamente, minimizando a sobrecarga na solicitação. No entanto, os dados no Memcache do App Engine podem ser eliminados periodicamente, o que significa que as informações da sessão serão perdidas. Para sessões de maior duração, talvez seja melhor usar um serviço de armazenamento alternativo, como o Cloud SQL.

Chaves especiais $_SERVER

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

  • APPLICATION_ID: o app_id do aplicativo definido quando ele foi criado. Por exemplo, my-wordpress.
  • AUTH_DOMAIN: o domínio usado para autenticar usuários com a API Users. Os aplicativos hospedados em appspot.com têm um AUTH_DOMAIN do gmail.com e aceitam qualquer Conta do Google. Os apps hospedados em um domínio personalizado que usa o Google Workspace têm um AUTH_DOMAIN igual ao domínio personalizado.
  • CURRENT_VERSION_ID: as versões principal e secundária do aplicativo em execução no momento, como "X.Y". O número principal da versão ("X") é especificado no arquivo app.yaml do aplicativo. O número da versão secundária ("Y") é definido automaticamente quando cada versão do aplicativo é enviada para o App Engine. No servidor da Web de desenvolvimento, a versão secundária é sempre "1".
  • DEFAULT_VERSION_HOSTNAME: o nome do host da versão padrão desse aplicativo. Por exemplo, my-php-app.uc.r.appspot.com.
  • HTTP_X_APPENGINE_CITY: nome da cidade de origem da solicitação. Por exemplo, uma solicitação da cidade de Mountain View talvez tenha o valor de cabeçalho "mountain view".
  • HTTP_X_APPENGINE_CITYLATLONG: latitude e longitude da cidade de origem da solicitação. Essa string pode parecer com "37.386051,-122.083851" para uma solicitação de Mountain View.
  • HTTP_X_APPENGINE_COUNTRY: país de origem da solicitação, como o código do país ISO 3166-1 alfa-2. O App Engine determina esse código com base no endereço IP do cliente.
  • HTTP_X_APPENGINE_REGION: nome da região de origem da solicitação. Esse valor só tem sentido no contexto do país em X-Appengine-Country. Por exemplo, se o país é "US" e a região é "ca", esse "ca" significa "Califórnia", não Canadá.
  • USER_EMAIL: retorna o endereço de e-mail do usuário, se ele tiver sido autenticado com a API Users. Os aplicativos precisam usar um apelido para os nomes de exibição.
  • USER_ID: se o endereço de e-mail estiver associado a uma Conta do Google, o user_id retornará o ID exclusivo permanente do usuário (ou uma string, se o usuário tiver sido autenticado usando a API Users). Este ID é sempre o mesmo para o usuário, mesmo que o usuário altere seu endereço de e-mail.
  • USER_IS_ADMIN: 1, se o usuário que fez login também for administrador do aplicativo (caso tenha sido autenticado por meio da API Users). Do contrário, 0.
  • USER_NICKNAME: para usuários das Contas do Google, o apelido é a parte do "nome" do endereço de e-mail do usuário, se o endereço estiver no mesmo domínio do aplicativo. Caso contrário, é o endereço de e-mail completo do usuário.
  • USER_ORGANIZATION: um aplicativo que usa a configuração das Contas do Google determina se o usuário que fez login no momento está usando uma Conta do Google pessoal ou uma conta gerenciada por um domínio do Google Workspace.

Comportamento de PHP_SELF e SCRIPT_NAME atualizado na versão 1.9.0

A implementação de $_SERVER['SCRIPT_NAME'] e $_SERVER['PHP_SELF'] anteriores à versão 1.9.0 é muito diferente da versão 1.9.0 em diante. As alterações foram feitas para ficarem consistentes com a implementação do Apache, que costuma ser esperada pelos aplicativos em PHP.

Veja a diferença nos exemplos a seguir.

Antes da 1.9.0Após a 1.9.0

app.yaml:

- url: /.*
  script: index.php
 
REQUEST_URI: /
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /
      PHP_SELF: /
 
REQUEST_URI: /
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /index.php
PHP_SELF: /index.php
 
REQUEST_URI: /bar
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /bar
PHP_SELF: /bar
 
REQUEST_URI: /bar
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /index.php
PHP_SELF: /index.php
 
REQUEST_URI: /index.php/foo/bar
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /index.php/foo/bar
PHP_SELF: /index.php/foo/bar
 
REQUEST_URI: /index.php/foo/bar
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /index.php
PHP_SELF: /index.php/foo/bar
 
REQUEST_URI: /test.php/foo/bar
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /test.php/foo/bar
PHP_SELF: /test.php/foo/bar
 
REQUEST_URI: /test.php/foo/bar
SCRIPT_FILENAME: /path/to/index.php
SCRIPT_NAME: /index.php
PHP_SELF: /index.php

app.yaml:

- url: /.*
  script: foo/index.php
 
REQUEST_URI: /bar
SCRIPT_FILENAME: /path/to/foo/index.php
SCRIPT_NAME: /bar
PHP_SELF: /bar
 
REQUEST_URI: /bar
SCRIPT_FILENAME: /path/to/foo/index.php
SCRIPT_NAME: /foo/index.php
PHP_SELF: /foo/index.php

Diretivas com novos padrões de inicialização

Esta tabela especifica diretivas que têm padrões de inicialização diferentes dos padrões fornecidos com o intérprete padrão do PHP disponível em php.net. É possível modificar essas diretivas padrão incluindo-as em um arquivo php.ini para seu aplicativo.

Diretiva Valor padrão no App Engine
detect_unicode false
session.gc_maxlifetime 600
session.cookie_secure 600
session.cookie_httponly 1
session.use_only_cookies 1
display_errors 0
display_startup_errors 0
html_errors 0
log_errors 1
file_uploads 0
upload_max_filesize 262144
max_file_uploads 0
date.timezone UTC
sendmail_path null
allow_url_fopen 1
allow_url_include 0
enable_dl 0
expose_php Off
register_globals Off
magic_quotes_gpc 0
mysqlnd.collect_statistics 0
mysql.allow_local_infile 0
mysqli.allow_local_infile 0

Funções desativadas

Por motivos de segurança ou para compatibilidade com o ambiente de execução do App Engine, algumas funções do PHP foram desativadas. Algumas dessas funções podem ser especificamente reativadas no arquivo php.ini do seu aplicativo.

Funções permanentemente desativadas

As seguintes funções foram desativadas permanentemente no App Engine:

  • disk_free_space()
  • disk_total_space()
  • diskfreespace()
  • escapeshellarg() and escapeshellcmd()
  • exec()
  • highlight_file()
  • lchgrp(), lchown(), link(), and symlink()
  • passthru()
  • pclose() and popen()
  • proc_close(), prog_get_status(), proc_nice(), proc_open(), and proc_terminate()
  • set_time_limit()
  • shell_exec()
  • show_source()
  • system()

O App Engine não inclui a pcntl (em inglês). Portanto, as funções fornecidas pelo pcntl não estão disponíveis para os aplicativos em PHP em execução no App Engine.

Compatibilidade de tempnam() e sys_get_temp_dir()

Os aplicativos do App Engine são executados em um sandbox de segurança que não permite gravar no sistema de arquivos local. Por isso, a versão do tempnam() do App Engine retorna um arquivo temporário na memória que pode ser gravado posteriormente em uma solução de armazenamento permanente, como os buckets do Google Cloud Storage.

Veja 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 é:

hello world

Funções parcialmente restritas

O ambiente de execução do App Engine para PHP não é compatível com o modificador de padrão /e das funções preg_replace() e mb_ereg_replace(). Consulte a documentação do PREG_REPLACE_EVAL para ver o aviso de suspensão de uso e um exemplo de como atualizar seu código para usar preg_replace_callback().

Funções que podem ser ativadas manualmente

Nessa lista, você verá que função do PHP é necessário ativar manualmente usando a diretiva google_app_engine.enable_functions no arquivo php.ini do seu aplicativo.

  • gc_collect_cycles(), gc_enable(), gc_disable() e gc_enabled()
  • getmypid()
  • getmyuid() e getmygid()
  • getrusage()
  • getmyinode()
  • get_current_user()
  • libxml_disable_entity_loader()*
  • parse_str()
  • phpinfo()
  • phpversion()
  • php_uname()
  • php_sapi_name()

Também é possível desativar funções manualmente usando a diretiva disable_functions no arquivo php.ini do seu aplicativo.

Funções que exigem faturamento ativado

As seguintes funções usam soquetes e, portanto, estão disponíveis apenas em aplicativos com faturamento ativado.

Suporte a stream

Wrappers de stream de E/S do PHP compatíveis

Os seguintes wrappers de stream de E/S do PHP são compatíveis:

  • php://input
  • php://output
  • php://memory
  • php://temp

Wrappers de stream

Muitas funções em PHP, como fopen() ou file_get_contents(), aproveitam a interface de streams do PHP para serem compatíveis com protocolos diferentes.

Veja a seguir uma lista de wrappers de stream integrados que são registrados automaticamente e estão disponíveis no ambiente de execução do App Engine.

Veja a seguir uma lista de gerenciadores de stream integrados que não são compatíveis com o App Engine e que tiveram o registro cancelado.

  • data://
  • expect://
  • ogg://
  • phar://
  • rar://
  • ssh2://

Transportes de stream desativados

Os transportes de stream abaixo foram desativados.

  • ssl
  • sslv2
  • sslv3
  • tcp
  • tls
  • udg
  • udp
  • unix

PHP puro

Todo o código referente ao ambiente de execução do PHP precisa ser de PHP puro. O App Engine não permite que você faça upload de suas próprias extensões C.

O ambiente inclui a biblioteca padrão do PHP. Algumas extensões foram desativadas porque as funções básicas delas não são compatíveis com o App Engine, como rede ou gravação no sistema de arquivos.

É possível incluir outras bibliotecas de PHP puro com seu aplicativo colocando o código no diretório do seu aplicativo, que é o mesmo diretório que contém seu arquivo app.yaml.

Por exemplo, é possível criar um link simbólico no diretório do seu aplicativo que aponte para o diretório de uma biblioteca. Esse link é seguido, e essa biblioteca é incluída no aplicativo quando você o implanta no App Engine.

Também é possível incluir bibliotecas de PHP especificando diretivas php.ini e incluindo instruções include do PHP no seu código. No entanto, a melhor alternativa é usar uma ferramenta de gerenciamento de dependências do PHP, como o Composer.

Exemplos:

  • Se você incluir o diretório raiz do aplicativo na diretiva include_path do seu arquivo php.ini:

    include_path=".:/[ROOT_DIR]/myapp"

    Em seguida, use as instruções include ou include_once para incluir arquivos PHP relativos ao seu include_path:

    include_once 'myfile.php';

  • Se você usar o Composer para incluir as bibliotecas de PHP puro, será possível simplesmente incluir um único arquivo depois que as dependências forem instaladas:

    require_once 'vendor/autoload.php';

    Ao usar o Composer para instalar as dependências do aplicativo, todos os pacotes serão adicionados ao diretório do aplicativo em vendor, que é onde o arquivo autoload.php será gerado.

Ferramentas

O SDK do App Engine inclui ferramentas para testar o aplicativo e fazer upload de arquivos de aplicativos.

O servidor de desenvolvimento executa o aplicativo no computador local para testá-lo.

A ferramenta gcloud gerencia todas as interações de linha de comando com o aplicativo em execução no App Engine. Use gcloud app deploy para fazer upload do seu aplicativo no App Engine ou para atualizar arquivos de configuração individuais. Também é possível ver os dados de registro do aplicativo para analisar o desempenho dele usando suas próprias ferramentas.

Código-fonte do interpretador do PHP

Você pode fazer o download do código-fonte do interpretador do PHP para App Engine no repositório appengine-php do GitHub.

Simultaneidade e latência

A latência do seu aplicativo tem o maior impacto no número de instâncias necessárias para disponibilizar o tráfego. Se você processa solicitações rapidamente, uma única instância pode manipular muitas solicitações.

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_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.

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