Aceda a serviços incluídos num pacote antigos para PHP

Esta página descreve como instalar e usar os serviços agrupados com o tempo de execução do PHP para o ambiente padrão do App Engine. A sua app pode aceder aos serviços incluídos através do SDK dos serviços do App Engine para PHP.

Antes de começar

1. Consulte a lista de APIs de serviços agrupados antigos que pode chamar no tempo de execução do PHP.

2. Atualize o ficheiro app.yaml para incluir a seguinte linha:

   app_engine_apis: true
   

3. Para testar a sua app PHP, tem de implementá-la através do gcloud app deploy.

Instalar o SDK do App Engine PHP

Pode encontrar o SDK do App Engine PHP no GitHub em appengine-php-sdk. Tem de usar a versão 2.1 ou posterior para o PHP 8.1 e a versão 2.0.1 ou posterior para o PHP 7.x.

Existem duas formas de incorporar o SDK no seu projeto:

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

   composer require google/appengine-php-sdk
   

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

   PHP 7/8

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

Em PHP, as APIs App Engine requerem a especificação explícita de dependências. Consulte este documento para obter instruções sobre como incluir autoload.php.

Importar as bibliotecas

Use o operador use para importar a classe de que precisa da lista de APIs disponíveis. Por exemplo, pode importar Google\AppEngine\Api\AppIdentity\ClassName com a declaração:

use Google\AppEngine\Api\AppIdentity\ClassName;

Considerações sobre a migração

Identidade da app

Não precisa de fazer alterações à configuração da sua app quando atualizar para o PHP. O comportamento, as funcionalidades e as instruções de configuração da API App Identity permanecem inalterados. Consulte a vista geral da identidade da API e o guia de referência da API App Identity para mais detalhes.

Correio

A API Mail do PHP permanece praticamente igual à API Mail do PHP 5, com algumas ligeiras diferenças na forma de ativar e desativar os serviços de correio. As secções seguintes abordam as diferenças entre ambos os tempos de execução.

Classe da mensagem

Em 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 não conseguir alterar as declarações de importação, a declaração de importação original do PHP 5.5 também funciona para o PHP.

Função de correio

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

Em PHP, a função App Engine Mail já não está sobrecarregada por predefinição e tem de ser ativada explicitamente. Este novo comportamento permite-lhe reutilizar a função de correio para se adequar melhor às suas necessidades. Esta alteração também lhe permite ter visibilidade sobre qual a implementação que está a ser usada atualmente para todas as chamadas de função de correio.

Se preferir usar a função mail() nativa do PHP para enviar correio através da API Mail do App Engine, pode ativá-la no ficheiro php.ini da seguinte forma:

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 mailparse para ativar a função de email PHP nativa e defina a configuração de tempo de execução sendmail_path para a implementação da função de email do App Engine. Depois de ativar esta opção, todas as chamadas para mail() vão funcionar exatamente como funcionavam no PHP 5.5.

Consulte os guias Enviar correio e Receber correio, bem como o guia de referência da API Mail para mais detalhes.

cache de memória

Para usar o Memcache para PHP, tem de adicionar uma declaração explícita das bibliotecas Memcache. Anteriormente, o Memcache para PHP 5.5 não requeria uma declaração explícita. Esta declaração explícita permite flexibilidade para alternar entre o Memcache PHP nativo e o Memcache do App Engine.

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

PHP 5.5

Exemplo de cache de memória 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 preferir usar o comportamento original do Memcache para PHP 5 no PHP, pode continuar a chamar o Memcache implicitamente incluindo mais algumas linhas no seu ficheiro composer.json. Depois de importar o pacote appengine-php-sdk do Composer, adicione o seguinte caminho do ficheiro de ativação à opção files no elemento 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 precisa de fazer alterações à configuração da sua app quando atualizar para o PHP. O comportamento, as funcionalidades e as instruções de configuração da API Modules permanecem inalterados. Consulte a vista geral dos módulos e o guia de referência da API Modules para mais detalhes.

Sessão

As sessões PHP funcionam da mesma forma que as sessões PHP 5.5. No entanto, as instruções de configuração são diferentes porque as sessões do PHP 5.5 usavam a classe MemcacheSessionHandler por predefinição.

Para usar sessões para PHP, tem de registar a classe MemcacheSessionHandler com session_set_save_handler() e configurar session.save_path para Memcache. Também deve ativar o Memcache quando acede a 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 Session para mais detalhes.

Fila de tarefas

Não precisa de fazer alterações à configuração da sua app quando atualizar para o PHP. O comportamento, as funcionalidades e as instruções de configuração da fila de tarefas permanecem inalterados. Consulte a secção Sessões no guia Vista geral da fila de tarefas e no guia de referência da API Task Queue para mais detalhes.

Obtenção de URL

Para usar a obtenção de URLs para PHP, tem de adicionar uma declaração explícita das bibliotecas de obtenção de URLs. Anteriormente, o serviço URL Fetch para PHP 5 não exigia uma declaração explícita e era usado implicitamente.

No PHP 5, o serviço URL Fetch do App Engine era a única forma de obter conteúdo da Internet no PHP 5.5, pelo que a maioria das funções do PHP 5.5 que acediam à Internet foram corrigidas para usar UrlFetch automaticamente.

No PHP, a rede PHP nativa pode aceder à Internet, pelo que esta aplicação de patches automática não é feita. Em alguns casos, pode usar o mecanismo original, em particular, o mecanismo que fornece o cabeçalho do pedido X-Appengine-Inbound-Appid para identificar a app do App Engine que está a fazer um pedido à sua app do App Engine.UrlFetch

Para ativar a obtenção de URLs para PHP, pode usar uma declaração explícita no wrapper de streams ou usar diretamente a classe UrlFetch, descrita nas secções seguintes.

Opção 1a. Controladores de streams

Pode ativar o serviço URL Fetch do App Engine para fazer pedidos HTTP aos processadores de streams PHP http:// e https://. Para o fazer:

1. Anule o registo do controlador de streams PHP nativo para HTTP(S) através de stream_wrapper_unregister().
2. Registe HTTP(S) na classe UrlFetchStream usando stream_wrapper_register().
3. Chame file_get_contents() com a configuração que quer usar o wrapper de streams.
   • Se quiser voltar ao controlador de streams PHP nativo do serviço URL Fetch, use stream_wrapper_unregister() e, em seguida, registe-se através de stream_wrapper_restore().

Para 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 controladores de streams

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

1. Anule o registo do controlador de streams PHP nativo para HTTP(S) através de stream_wrapper_unregister().
2. Registe HTTP(S) na UrlFetchStreamclasse através de stream_wrapper_register().
3. Use fopen() em vez de file_get_contents() com a configuração pretendida.
4. Chame stream_get_meta_data() e extraia as informações do cabeçalho da resposta indexando os metadados para 'wrapper_data. Os cabeçalhos de resposta são devolvidos num formato de matriz semelhante ao 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 oferece uma forma mais segmentada de usar o serviço URL Fetch para um pedido HTTP(S) num âmbito mais reduzido. Ao contrário da opção de controlador de streams, a classe UrlFetch não substitui todos os pedidos HTTP(S) feitos a partir de funções compatíveis com o wrapper de streams para usar o serviço URL Fetch. Em comparação com a opção de controlador de streams, a configuração da classe UrlFetch também é mais simples, uma vez que não requer a utilização de várias APIs PHP, como:

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

O seguinte exemplo de classe UrlFetch é equivalente ao exemplo de controlador de streams:

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();

Utilizadores

Não precisa de fazer alterações à configuração da sua app quando atualizar para o PHP. O comportamento, as funcionalidades e as instruções de configuração da API Users permanecem iguais. Consulte a vista geral da API Users e o guia de referência da API Users para mais detalhes.

Bibliotecas contribuídas pela comunidade

Pode usar a API contribuída pela comunidade para datastore quando atualizar para PHP.

Outras considerações

• Para testar a funcionalidade dos serviços agrupados antigos na sua app PHP, pode usar o servidor de desenvolvimento local. Quando executar o comando dev_appserver.py, defina o argumento --php_executable_path para um executável PHP. Tenha em atenção que isto é diferente do PHP 5, que requer um executável php-cgi.

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

• Para implementar a sua app, use o comando gcloud app deploy.

• O registo no tempo de execução do PHP segue a norma de registo no Cloud Logging. No tempo de execução do PHP, os registos da app deixaram de ser agrupados com os registos de pedidos, mas são separados em registos diferentes. Para saber mais sobre como ler e escrever registos, consulte o guia de escrita e visualização de registos.

Exemplos

Para ver exemplos de como usar os serviços agrupados antigos com PHP, transfira os exemplos de código.