Acessar serviços agrupados legados para PHP

Nesta página, descrevemos como instalar e usar os serviços incluídos com o ambiente de execução do PHP para o ambiente padrão do App Engine. O aplicativo pode acessar os serviços no pacote por meio do SDK de serviços do App Engine para PHP.

Antes de começar

1. Consulte a lista de APIs legadas de serviços em pacote que podem ser chamadas no ambiente de execução do PHP.

2. Atualize o arquivo app.yaml para incluir esta linha:

   app_engine_apis: true
   

3. Para testar o aplicativo PHP, você precisa implantá-lo usando gcloud app deploy.

Como instalar o SDK do App Engine para PHP

Você encontra o SDK do App Engine para PHP no GitHub em appengine-php-sdk. Você precisa usar a versão 2.1 ou posterior para PHP 8.1+ e a versão 2.0.1 ou posterior para PHP 7.x.

Há duas maneiras de incorporar o SDK no projeto:

1. Execute o comando Packagist para adicionar o SDK ao arquivo composer.json:

   composer require google/appengine-php-sdk
   

2. Crie manualmente um arquivo composer.json com os seguintes detalhes:

   PHP 7/8

   {
       "require": {
           "google/appengine-php-sdk": "^2.1" // Or any later version
       }
   }
   

No PHP, as APIs do App Engine exigem uma especificação de dependência explícita. Consulte este documento para ver instruções sobre como incluir autoload.php.

Como importar as bibliotecas

Use o operador use para importar a classe necessária da lista de APIs disponíveis. Por exemplo, Google\AppEngine\Api\AppIdentity\ClassName pode ser importado com a instrução:

use Google\AppEngine\Api\AppIdentity\ClassName;

Considerações sobre a migração

Identidade do aplicativo

Não é necessário alterar as configurações do aplicativo ao fazer upgrade para o PHP. O comportamento, os recursos e as instruções de configuração da API App Identity permanecem os mesmos. Consulte a Visão geral da identidade da API e o Guia de referência da API App Identity para mais detalhes.

E-mail

A API Mail do PHP continua a mesma da API Mail 5 do PHP, com algumas pequenas diferenças em como ativar e desativar os serviços do Mail. Nas seções a seguir, mostramos as diferenças entre os dois tempos de execução.

Classe de mensagem

No PHP, a classe Message funciona da mesma forma que no PHP 5.5, exceto que as importações use foram atualizadas. As diferenças são as seguintes:

PHP 5.5

use google\appengine\api\mail\Message;

PHP 7/8

use Google\AppEngine\Api\Mail\Message;

Se você não conseguir alterar as instruções de importação, a instrução de importação original do PHP 5.5 também funcionará para o PHP.

Função de e-mail

No PHP 5.5, a função mail() nativa do PHP foi sobrecarregada pela função de e-mail do App Engine.

No PHP, a função de e-mail do App Engine não está mais sobrecarregada por padrão e precisa ser ativada explicitamente. Esse novo comportamento permite que você reutilize essa função para atender melhor às suas necessidades. Essa alteração também permite que você tenha visibilidade de qual implementação está sendo usada atualmente para todas as chamadas de função de e-mail.

Se você preferir usar a função nativa do PHP mail() para enviar e-mails usando a API Mail do App Engine, será possível ativá-la no arquivo php.ini da seguinte maneira:

extension = mailparse.so
sendmail_path = "php ./vendor/google/appengine-php-sdk/src/Runtime/SendMail.php -t -i"

Conforme mostrado no exemplo anterior, adicione a extensão do mailparse para ativar a função de e-mail nativa do PHP e defina a configuração do ambiente de execução do sendmail_path como a implementação da função de e-mail do App Engine. Depois de ativar essa opção, todas as chamadas para mail() funcionarão exatamente como no PHP 5.5.

Para mais detalhes, consulte os guias Como enviar e-mails e Como receber e-mails e o Guia de referência da API Mail.

Memcache

Para usar o Memcache para PHP, é necessário adicionar uma declaração explícita das bibliotecas do Memcache. Anteriormente, o Memcache para PHP 5.5 não exigia uma declaração explícita. Essa declaração explícita permite flexibilidade para alternar entre o Memcache do PHP nativo e o Memcache do App Engine.

As classes do Memcache do PHP têm o mesmo comportamento que as classes do Memcache do PHP 5, com exceção da declaração explícita. Consulte a Visão geral do Memcache para mais detalhes.

PHP 5.5

Exemplo do Memcache para PHP 5.5:

$memcache = new Memcache();
return $memcache->get($key);

Exemplo do Memcached para PHP 5.5:

$memcache = new Memcached();
$memcache->set('who', $request->get('who'));
return $twig->render('memcache.html.twig', [
    'who' => $request->get('who'),
    'count' => $memcache->increment('count', 1, 0),
    'host' => $request->getHost(),
]);

PHP 7/8

Exemplo da API Memcache para PHP:

use Google\AppEngine\Api\Memcache\Memcache;

$memcache = new Memcache();
return $memcache->get($key);

Exemplo da API Memcached para PHP:

use Google\AppEngine\Api\Memcache\Memcached;

$memcache = new Memcached();
$memcache->set('who', $request->get('who'));
return $twig->render('memcache.html.twig', [
    'who' => $request->get('who'),
    'count' => $memcache->increment('count', 1, 0),
    'host' => $request->getHost(),
]);

Se você preferir usar o comportamento original do Memcache para PHP 5 no PHP, continue chamando o Memcache implicitamente incluindo mais algumas linhas no arquivo composer.json. Depois de importar o pacote appengine-php-sdk do compositor, adicione o seguinte caminho de arquivo de ativação ao elemento files na seção autoload:

PHP 7/8

{
  "require": {
    "google/appengine-php-sdk": "^2.1" // Or any later version
  },
  "autoload": {
    "files": [
    "./vendor/google/appengine-php-sdk/src/Api/Memcache/MemcacheOptIn.php"
    ]
  }
}

Módulos

Não é necessário alterar as configurações do aplicativo ao fazer upgrade para o PHP. O comportamento, os recursos e as instruções de configuração da API Modules permanecem os mesmos. Consulte a Visão geral dos módulos e o Guia de referência da API Modules para mais detalhes.

Sessão

O PHP Sessions funciona da mesma maneira que o PHP 5.5 Sessions. No entanto, as instruções de configuração são diferentes porque as sessões do PHP 5.5 usaram a classe MemcacheSessionHandler por padrão.

Para usar sessões para PHP, você precisa registrar a classe MemcacheSessionHandler com session_set_save_handler() e com session.save_path para o Memcache. Você também deve ativar o Memcache ao acessar as informações do Memcache.

Por exemplo:

PHP 7/8

ini_set('session.save_path', 'Google\AppEngine\Api\Memcache\Memcache');
session_set_save_handler(new Google\AppEngine\Ext\Session\MemcacheSessionHandler(), true);

Consulte o Guia de referência da API da sessão para mais detalhes.

Fila de tarefas

Não é necessário alterar as configurações do aplicativo ao fazer upgrade para o PHP. O comportamento, os recursos e as instruções de configuração da fila de tarefas permanecem os mesmos. Consulte a seção "Sessões" no guia Visão geral da fila de tarefas e Guia de referência da API Task Queue para mais detalhes.

Busca de URL

Para usar a busca de URL do PHP, é necessário adicionar uma declaração explícita das bibliotecas de busca de URL. Antes, o serviço de busca de URL do PHP 5 não exigia uma declaração explícita e era usado implicitamente.

No PHP 5, o serviço de busca de URL do App Engine era a única maneira de buscar conteúdo de Internet no PHP 5.5. Portanto, a maioria das funções do PHP 5.5 que acessavam a Internet foi corrigida para usar UrlFetch automaticamente.

No PHP, a rede nativa do PHP pode acessar a Internet, portanto, essa correção automática não é feita. Em alguns casos, é possível usar o mecanismo UrlFetch original, principalmente o mecanismo que fornece o cabeçalho da solicitação X-Appengine-Inbound-Appid para identificar o aplicativo do App Engine que faz uma solicitação para o aplicativo do App Engine.

Para ativar a busca de URL do PHP, use uma declaração explícita no wrapper de stream ou use a classe UrlFetch diretamente, descrita nas seções a seguir.

Opção 1a. Gerenciadores de stream

É possível ativar o serviço de busca de URL do App Engine para fazer solicitações HTTP a gerenciadores de stream PHP http:// e https://. Para isso, siga estas etapas:

1. Cancele o registro do gerenciador de stream nativo do PHP para HTTP(S) usando stream_wrapper_unregister().
2. Registre HTTP(S) na classe UrlFetchStream usando stream_wrapper_register().
3. Chame file_get_contents() com a configuração que você quer usar o wrapper de stream.
   • Se você quiser voltar a usar o gerenciador de stream nativo do PHP no serviço de busca de URL, use stream_wrapper_unregister() e registre-se usando stream_wrapper_restore().

Para uma comparação, consulte os exemplos equivalentes para PHP 5 e PHP:

PHP 5.5

...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using Url Fetch service. No option to use the native php stream wrapper.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

PHP 7/8

use google\appengine\api\urlfetch\UrlFetchStream;
...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using the native php stream wrapper.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

stream_wrapper_unregister("http");
stream_wrapper_register("http", "UrlFetchStream");

// Now using the Url Fetch service.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

stream_wrapper_unregister("http");
stream_wrapper_restore("http");

// Now using the native php stream wrapper again.

Opção 1b. Cabeçalhos de resposta HTTP com gerenciadores de stream

As instruções para usar cabeçalhos de resposta HTTP(S) com gerenciadores de stream são semelhantes às instruções para usar gerenciadores de stream:

1. Cancele o registro do gerenciador de stream PHP nativo para HTTP(S) usando stream_wrapper_unregister().
2. Registre HTTP(S) na classe UrlFetchStream usando stream_wrapper_register().
3. Use fopen() em vez de file_get_contents() com a configuração que você quer.
4. Chame stream_get_meta_data() e extraia as informações do cabeçalho de resposta indexando metadados para 'wrapper_data. Os cabeçalhos de resposta são retornados em uma forma de matriz semelhante à de $http_response_header no PHP 5.5.

PHP 5.5

...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using file_get_contents and the Url Fetch service.
$result = file_get_contents('http://example.com', false, $context);

// Print Http Response Headers
print_r($http_response_header);

PHP 7/8

use google\appengine\api\urlfetch\UrlFetchStream;
...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

stream_wrapper_unregister("http");
stream_wrapper_register("http", "UrlFetchStream");

// Now using fopen and the Url Fetch service.
$result = fopen('http://example.com', 'r', false, $context);

// Print Http Response Headers
$meta_data = stream_get_meta_data($result);
$headers = $meta_data['wrapper_data'];
print_r($headers);

stream_wrapper_unregister("http");
stream_wrapper_restore("http");

Opção 2. Classe UrlFetch

A classe UrlFetch é uma classe personalizada que fornece uma forma mais segmentada de usar o serviço de busca de URL para uma solicitação HTTP(S) em um escopo menor. Ao contrário da opção do gerenciador de stream, a classe UrlFetch não substitui todas as solicitações HTTP(S) feitas de funções compatíveis com o wrapper de stream para usar o serviço de busca de URL. Em comparação com a opção de gerenciador de stream, a configuração da classe UrlFetch também é mais simples, já que não requer o uso de várias APIs PHP, como:

• stream_context_create()
• stream_wrapper_unregister()
• stream_wrapper_register()
• file_get_contents()

O exemplo de classe UrlFetch a seguir é equivalente ao exemplo de gerenciador de stream:

PHP 7/8

use google\appengine\api\urlfetch\UrlFetch;
...
$urlfetch = new UrlFetch();
$result = $urlfetch->fetch($url, 'POST', $headers, http_build_query($data));
echo $result->getContent();

Usuários

Não é necessário alterar as configurações do aplicativo ao fazer upgrade para o PHP. O comportamento, os recursos e as instruções de configuração da API Users permanecem os mesmos. Consulte a Visão geral da API Users e o Guia de referência da API Users para mais detalhes.

Bibliotecas fornecidas pela comunidade

É possível usar a API fornecida pela comunidade para datastore ao fazer upgrade para o PHP.

Outras considerações

• Para testar a funcionalidade dos serviços incluídos legados no app PHP, use o servidor de desenvolvimento local. Ao executar o comando dev_appserver.py, defina o argumento --php_executable_path como um executável do PHP. Isso é diferente do PHP 5, que requer um executável php-cgi.

  Se o projeto tiver um arquivo composer.json, defina --php-composer-path como o caminho do arquivo composer.phar.

• Para implantar o aplicativo, use o comando gcloud app deploy.

• A geração de registros no ambiente de execução do PHP segue o padrão de geração de registros no Cloud Logging. No ambiente de execução do PHP, os registros de aplicativos não são mais incluídos com os registros de solicitação, mas são separados em registros diferentes. Para saber mais sobre como ler e gravar registros, consulte o guia Como gravar e visualizar registros.

Exemplos

Para ver exemplos de como usar os serviços agrupados legados com o PHP, faça o download das amostras de código.