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.

Consulte o guia de primeiros passos do PHP para uma introdução ao desenvolvimento de aplicativos da Web com PHP e App Engine.

Como selecionar o ambiente de execução do PHP

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

Para configurar o aplicativo para usar o ambiente de execução do PHP, inclua a seguinte instrução no 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 a versão do ambiente de execução do PHP que será usada. Quando este documento foi elaborado, o App Engine só tinha uma versão do ambiente do PHP, 1. Se houver alterações futuras que possam não ser compatíveis com versões anteriores, a equipe do App Engine usará um novo identificador de versão. O aplicativo continuará usando a versão selecionada até você alterar a configuração api_version e fazer upload dele.

Para mais informações sobre o arquivo app.yaml e como implantar o aplicativo no App Engine, consulte os tópicos Referência do app.yaml e Como implantar um aplicativo 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 você não precisa usar as instruções include ou require na parte superior dos scripts PHP.

Por padrão, o carregamento automático de classes ocorrerá apenas para as classes definidas nos arquivos que residem no diretório raiz da raiz do SDK do App Engine e, se tiver sido especificado por --php_executable_path, na sua instalação local do PHP.

Para incluir mais caminhos na pesquisa do carregamento automático de classes, 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
  • calendar
  • Core
  • ctype
  • date
  • dom
  • ereg
  • exif
  • filter
  • ftp
  • gd
  • hash
  • iconv
  • json
  • libxml
  • mailparse
  • mbstring
  • mcrypt
  • memcache
  • memcached
  • mysql
  • mysqli
  • mysqlnd
  • OAuth
  • openssl
  • pcre
  • PDO
  • pdo_mysql
  • Reflection
  • session
  • shmop
  • SimpleXML
  • soap
  • sockets (para aplicativos com faturamento ativado)
  • SPL
  • standard
  • tokenizer
  • xml
  • xmlreader
  • xmlwriter
  • xsl
  • zip
  • zlib

Extensões dinamicamente carregáveis

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

  • cURL: essa extensão usa o serviço de soquete para fazer solicitações. Ela está sujeita à cota e às restrições desse serviço e está disponível somente para aplicativos com faturamento ativado. Consulte Solicitações de saída para mais informações.
  • MongoDB: essa extensão permite que um desenvolvedor se conecte a uma instância atual do MongoDB. Ela usa o serviço de soquete para fazer solicitações, está sujeita à cota e às restrições desse serviço e está disponível somente para aplicativos com faturamento ativado.
  • ImageMagick
  • intl
  • fileinfo

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

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 por meio da classe MemcacheSessionHandler. Para ajustar esse comportamento, especifique o gerenciador de sessão 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 mais longas, talvez seja melhor usar um serviço de armazenamento alternativo, como o Cloud SQL.

Chaves especiais $_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 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 aplicativos hospedados em um domínio personalizado que usa o G Suite 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 da versão principal ("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.appspot.com.
  • HTTP_X_APPENGINE_CITY: nome da cidade de origem da solicitação. Por exemplo, uma solicitação da cidade de Mountain View pode ter o valor de cabeçalho "mountain view".
  • HTTP_X_APPENGINE_CITYLATLONG: latitude e longitude da cidade de origem da solicitação. Essa string pode ter o formato parecido 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 faz sentido apenas 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", e não Canadá.
  • USER_EMAIL: retorna o endereço de e-mail do usuário, caso ele tenha sido autenticado por meio da 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, user_id retornará o ID permanente e exclusivo do usuário, um str. Se ele foi autenticado por meio da API Users. Esse código é sempre igual para o usuário, mesmo que ele altere o endereço de e-mail.
  • USER_IS_ADMIN: 1 se o usuário que fez login é também administrador do aplicativo (caso tenha sido autenticado por meio da API Users). Caso 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 de Contas do Google pode determinar se o usuário que fez login no momento está utilizando uma conta do Google pessoal ou uma conta gerenciada por um domínio do G Suite.

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'] anterior à 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 as diretivas que têm padrões de inicialização diferentes daqueles fornecidos com o interpretador do PHP padrão disponível no php.net. Você pode substituir essas diretivas padrão incluindo-as em um arquivo php.ini do 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 extensão 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.

Suporte a 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 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 intervalos do Google Cloud Storage.

Veja a seguir 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 então:

hello world

Funções parcialmente restritas

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

Funções que podem ser ativadas manualmente

Nesta lista, são especificadas funções do PHP que precisam ser ativadas manualmente usando a diretiva google_app_engine.enable_functions no arquivo php.ini do 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 manualmente as funções por meio da diretiva disable_functions no arquivo php.ini do 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 no PHP, como fopen() ou file_get_contents(), aproveitam a interface dos streams do PHP para aceitar diferentes protocolos.

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.

  • file://
  • glob://
  • http://: o funcionamento dele é parecido com o do gerenciador de stream HTTP integrado do PHP, mas usa o serviço URLfetch do App Engine
  • https://: usa o serviço URLfetch do App Engine
  • ftp://
  • gs://: o gerenciador de stream do Google Cloud Storage
  • zlib://

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.

Você pode incluir outras bibliotecas de PHP puro em seu aplicativo colocando o código no diretório do aplicativo, que é o mesmo que contém o arquivo app.yaml.

Por exemplo, você pode criar um link simbólico no diretório do 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.

Você também pode incluir bibliotecas do PHP especificando as diretivas php.ini e inserindo as instruções include do PHP no código. No entanto, a alternativa preferida é usar uma ferramenta de gerenciamento de dependências de PHP, como o Composer.

Exemplos:

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

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

    Será possível então usar as instruções include ou include_once para incluir arquivos PHP relativos ao 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';
    

    Quando você usa o Composer para instalar as dependências do aplicativo, todos os pacotes são adicionados ao diretório do aplicativo em vendor, que também é onde o arquivo autoload.php é 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 processa todas as interações de linha de comando com o aplicativo em execução no App Engine. Use o comando gcloud app deploy para fazer upload do aplicativo no App Engine ou para atualizar arquivos de configuração individuais. É possível também ver os dados de registro do aplicativo. Portanto, você pode 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 lidar com muitas solicitações.