PHP 5 Runtime Environment

Com o App Engine, pode criar aplicações Web através da linguagem de programação PHP. A sua aplicação PHP é executada na infraestrutura escalável da Google e usa armazenamento persistente e serviços em grande escala.

Selecionar o tempo de execução do PHP

O App Engine executa a sua aplicação Web PHP através de um intérprete da versão 5.5.34 do PHP. Nota: no Linux, também tem de instalar o PHP localmente para executar as suas apps PHP.

Para definir a sua app para usar o tempo de execução do PHP, adicione o seguinte ao ficheiro 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 a usar. No momento da redação deste artigo, o App Engine só tem uma versão do ambiente PHP, a 1. Se houver alterações futuras que possam não ser retrocompatíveis, a equipa do App Engine vai usar um identificador de nova versão. A sua app vai continuar a usar a versão selecionada até alterar a definição api_version e carregar a app.

Para mais informações sobre o ficheiro app.yaml e como implementar a sua app no App Engine, consulte os tópicos app.yaml de referência e Implementar uma app PHP.

A sandbox

Para permitir que o App Engine distribua pedidos de aplicações por vários servidores Web e para impedir que uma aplicação interfira com outra, a aplicação é executada num ambiente de "isolamento de processos" (sandbox) restrito. Neste ambiente, a aplicação pode executar código, usar os serviços de correio, obtenção de URLs e utilizadores do App Engine, bem como examinar o pedido Web do utilizador e preparar a resposta.

Uma aplicação do App Engine não pode:

  • escrever no sistema de ficheiros. As aplicações PHP podem usar o Google Cloud Storage para armazenar ficheiros persistentes. A leitura do sistema de ficheiros é permitida e todos os ficheiros da aplicação carregados com a aplicação estão disponíveis.

  • responder lentamente. Um pedido Web a uma aplicação tem de ser processado em alguns segundos. Os processos que demoram muito tempo a responder são terminados para evitar sobrecarregar o servidor Web.

  • Fazer outros tipos de chamadas de sistema.

Carregamento automático de turmas

As classes da Standard PHP Library (SPL) e todas as classes que fazem parte do SDK do App Engine são carregadas automaticamente quando necessário. Isto significa que não tem de usar declarações include ou require na parte superior dos seus scripts PHP.

Por predefinição, o carregamento automático de classes ocorre apenas para classes definidas em ficheiros que residam no diretório raiz do SDK para a raiz do App Engine (e, se tiver sido especificado por --php_executable_path, a sua instalação local do PHP).

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

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

Extensões ativadas

As seguintes extensões foram ativadas no tempo de execução do PHP para o App Engine:

  • apc
  • bcmath
  • calendário
  • Principal
  • ctype
  • data
  • dom
  • ereg
  • exif
  • filtrar
  • 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
  • sabonete
  • Entradas (para apps com faturação ativada)
  • SPL
  • padrão
  • tokenizador
  • xml
  • xmlreader
  • xmlwriter
  • xsl
  • código postal
  • zlib

Extensões carregáveis dinamicamente

As seguintes extensões são carregáveis dinamicamente através da configuração de php.ini.

Para ativar estas extensões, adicione diretivas para as mesmas no seu ficheiro 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 das aplicações Web precisa de uma forma de preservar as informações de estado do utilizador entre pedidos. O PHP oferece uma camada de gestão de sessões conveniente. As sessões no App Engine funcionam de forma semelhante às sessões em qualquer outra aplicação PHP.

Definir uma variável na sessão de um utilizador:

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

Num pedido subsequente do mesmo utilizador:

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

Por predefinição, o tempo de execução do App Engine usa a cache de memória para armazenar informações de sessão através da classe MemcacheSessionHandler. Pode ajustar este comportamento especificando o seu próprio controlador de sessão através do método session_set_save_handler() do PHP. O Memcache permite que os dados da sessão sejam guardados e obtidos rapidamente, o que significa que a sobrecarga no seu pedido é mínima. No entanto, os dados na cache do App Engine podem ser limpos periodicamente, o que significa que as informações da sessão são perdidas. Para sessões mais longas, pode ser preferível usar um serviço de armazenamento alternativo, como o Cloud SQL.

Chaves $_SERVER especiais

O PHP disponibiliza a matriz especial $_SERVER[] no âmbito do pedido. Além dos parâmetros CGI padrão, o App Engine adiciona algumas chaves úteis adicionais.

  • APPLICATION_ID – O app_id da aplicação definido quando a app foi criada. Por exemplo, my-wordpress
  • AUTH_DOMAIN: o domínio usado para autenticar utilizadores com a API Users. As apps alojadas em appspot.com têm um AUTH_DOMAIN de gmail.com e aceitam qualquer Conta Google. As apps alojadas num domínio personalizado através do Google Workspace têm um AUTH_DOMAIN igual ao domínio personalizado
  • CURRENT_VERSION_ID: a versão principal e secundária da aplicação atualmente em execução, como "X.Y". O número da versão principal ("X") é especificado no ficheiro app.yaml da app. O número da versão secundária ("Y") é definido automaticamente quando cada versão da app é carregada no App Engine. No servidor Web de programação, a versão secundária é sempre "1".
  • DEFAULT_VERSION_HOSTNAME - O nome de anfitrião da versão predefinida desta aplicação, por exemplo, my-php-app.uc.r.appspot.com.
  • HTTP_X_APPENGINE_CITY - Nome da cidade de origem do pedido. Por exemplo, um pedido da cidade de Mountain View pode ter o valor do cabeçalho mountain view.
  • HTTP_X_APPENGINE_CITYLATLONG – Latitude e longitude da cidade de origem do pedido. Esta string pode ter o seguinte aspeto: "37.386051,-122.083851" para um pedido de Mountain View.
  • HTTP_X_APPENGINE_COUNTRY – País de origem do pedido, como um código do país ISO 3166-1 alfa-2. O App Engine determina este código a partir do endereço IP do cliente.
  • HTTP_X_APPENGINE_REGION - Nome da região de origem do pedido. Este 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" significa "Califórnia" e não Canadá.
  • USER_EMAIL - Devolve o endereço de email do utilizador, se este tiver sido autenticado através da API Users. As aplicações devem usar a alcunha para nomes apresentáveis.
  • USER_ID - Se o endereço de email estiver associado a uma Conta Google, user_id devolve o ID permanente exclusivo do utilizador, um str. Se tiverem sido autenticados através da API Users. Este ID é sempre o mesmo para o utilizador, independentemente de este alterar o respetivo endereço de email.
  • USER_IS_ADMIN - 1 se o utilizador com sessão iniciada também for um administrador da aplicação, se tiver sido autenticado através da API Users. Caso contrário, 0.
  • USER_NICKNAME - Para utilizadores de Contas Google, o pseudónimo é a parte "nome" do endereço de email do utilizador se o endereço estiver no mesmo domínio que a aplicação ou o endereço de email completo do utilizador, caso contrário.
  • USER_ORGANIZATION - Uma aplicação que use a definição Contas Google pode determinar se o utilizador com sessão iniciada está a usar uma Conta Google pessoal ou uma conta gerida por um domínio do Google Workspace.

Comportamento atualizado de PHP_SELF e SCRIPT_NAME na versão 1.9.0

A implementação de $_SERVER['SCRIPT_NAME'] e $_SERVER['PHP_SELF'] antes da versão 1.9.0 difere significativamente da versão 1.9.0 e posteriores. As alterações foram feitas para serem consistentes com a implementação do Apache geralmente esperada pelas aplicações PHP.

Os exemplos seguintes demonstram a diferença.

Antes da versão 1.9.0Após 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 valores predefinidos de inicialização

Esta tabela especifica diretivas cujas predefinições de inicialização diferem das predefinições fornecidas com o intérprete PHP padrão disponível em php.net. Pode substituir estas diretivas predefinidas incluindo-as num ficheiro php.ini para a sua aplicação.

Diretiva Valor predefinido 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 de compatibilidade com o ambiente de execução do App Engine, algumas funções PHP foram desativadas. Algumas destas funções podem ser explicitamente reativadas no ficheiro php.ini para a sua aplicação.

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 e, por isso, as funções fornecidas por pcntl não estão disponíveis para apps PHP em execução no App Engine.

Compatibilidade com tempnam() e sys_get_temp_dir()

As apps do App Engine são executadas numa sandbox de segurança que não permite a escrita no sistema de ficheiros local. Por este motivo, a versão do App Engine de tempnam() devolve um ficheiro temporário na memória que pode ser escrito numa solução de armazenamento permanente, como contentores do Google Cloud Storage mais tarde.

Segue-se um exemplo de como escrever no ficheiro temporário na memória através de 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);

O resultado esperado do exemplo seria:

hello world

Funções parcialmente restritas

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

Funções que podem ser ativadas manualmente

Esta lista especifica a função PHP que tem de ser ativada manualmente através da diretiva google_app_engine.enable_functions no ficheiro php.ini da sua aplicação.

  • 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 pode desativar manualmente as funções através da diretiva disable_functions no ficheiro php.ini da sua aplicação.

Funções que requerem a faturação ativada

As seguintes funções usam Sockets e, por isso, só estão disponíveis para apps com faturação ativada.

Suporte de streams

Wrappers de streams de E/S de PHP suportados

Os seguintes wrappers de streams de E/S de PHP são suportados:

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

Wrappers de stream

Muitas funções no PHP, como fopen() ou file_get_contents(), tiram partido da interface de streams do PHP para suportar diferentes protocolos.

Segue-se uma lista de wrappers de streams incorporados que são registados automaticamente e estão disponíveis no tempo de execução do App Engine.

  • file://
  • glob://
  • http:// (Este comportamento é semelhante ao controlador de streams http incorporado do PHP, mas usa o serviço URLfetch do App Engine)
  • https:// (Isto usa o serviço URLfetch do App Engine)
  • ftp://
  • gs:// (O controlador de streams para o Google Cloud Storage)
  • zlib://

Segue-se uma lista de controladores de streams incorporados que não são suportados no App Engine e foram anularam o registo.

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

Transportes de streams desativados

Os seguintes transportes de streams foram desativados.

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

PHP puro

Todo o código para o ambiente de execução PHP tem de ser PHP puro. O App Engine não permite carregar as suas próprias extensões C.

O ambiente inclui a biblioteca padrão do PHP. Algumas extensões foram desativadas porque as respetivas funções principais não são suportadas pelo App Engine, como a rede e a escrita no sistema de ficheiros.

Pode incluir outras bibliotecas PHP puras na sua aplicação colocando o código no diretório da aplicação, que é o mesmo diretório que contém o ficheiro app.yaml.

Por exemplo, pode criar uma ligação simbólica no diretório da sua aplicação que aponte para o diretório de uma biblioteca. Em seguida, esse link é seguido e essa biblioteca é incluída na sua aplicação quando a implementa no App Engine.

Também pode incluir bibliotecas PHP especificando diretivas php.ini e incluindo declarações include PHP no seu código. No entanto, a alternativa preferencial é usar uma ferramenta de gestão de dependências do PHP, como o Composer.

Exemplos:

  • Se incluir o diretório raiz da sua aplicação na diretiva include_path do ficheiro php.ini:

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

    Em seguida, pode usar as declarações include ou include_once para incluir ficheiros PHP relativos ao seu include_path:

    include_once 'myfile.php';

  • Se optar por usar o Composer para incluir as suas bibliotecas PHP puras, pode simplesmente incluir um único ficheiro depois de as dependências serem instaladas:

    require_once 'vendor/autoload.php';

    Quando usa o Composer para instalar as dependências da sua aplicação, todos os pacotes são adicionados no diretório da aplicação em vendor, que é também onde o ficheiro autoload.php é gerado.

Ferramentas

O SDK do App Engine inclui ferramentas para testar a sua aplicação e carregar ficheiros de aplicações.

O servidor de desenvolvimento executa a sua aplicação no computador local para testar a aplicação.

A ferramenta gcloud processa todas as interações de linha de comandos com a sua aplicação em execução no App Engine. Use gcloud app deploy para carregar a sua aplicação para o App Engine ou para atualizar ficheiros de configuração individuais. Também pode ver os dados de registo da sua app para analisar o desempenho da app com as suas próprias ferramentas.

Código-fonte do intérprete de PHP

Pode transferir o código fonte do intérprete PHP do App Engine no repositório appengine-php no GitHub.

Simultaneidade e latência

A latência da sua aplicação tem o maior impacto no número de instâncias necessárias para publicar o seu tráfego. Se processar pedidos rapidamente, uma única instância pode processar muitos pedidos.

Variáveis de ambiente

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

Variável de ambiente Descrição
GAE_APPLICATION O ID da sua aplicação do App Engine. Este ID tem o prefixo "region code~", como "e~" para aplicações implementadas na Europa.
GAE_DEPLOYMENT_ID O ID da implementação atual.
GAE_ENV O ambiente do App Engine. Definido como standard.
GAE_INSTANCE O ID da instância na qual o seu serviço está atualmente em execução.
GAE_RUNTIME O tempo de execução especificado no ficheiro app.yaml.
GAE_SERVICE O nome do serviço especificado no ficheiro app.yaml. Se não for especificado nenhum nome de serviço, este é definido como default.
GAE_VERSION A etiqueta da versão atual do seu serviço.
GOOGLE_CLOUD_PROJECT O Google Cloud ID do projeto associado à sua aplicação.
PORT A porta que recebe pedidos HTTP.

Pode definir variáveis de ambiente adicionais no seu ficheiro app.yaml, mas os valores acima não podem ser substituídos.