Accedere ai servizi in bundle legacy per PHP

Questa pagina descrive come installare e utilizzare i servizi in bundle con il runtime PHP per l'ambiente standard di App Engine. La tua app può accedere ai servizi integrati tramite l'SDK dei servizi App Engine per PHP.

Prima di iniziare

1. Consulta l'elenco delle API dei servizi in bundle legacy che puoi chiamare nel runtime PHP.

2. Aggiorna il file app.yaml per includere la seguente riga:

   app_engine_apis: true
   

3. Per testare la tua app PHP, devi eseguirne il deployment utilizzando gcloud app deploy.

Installazione dell'SDK App Engine per PHP

Puoi trovare l'SDK App Engine per PHP su GitHub all'indirizzo appengine-php-sdk. Devi utilizzare la versione 2.1 o successive per PHP 8.1+ e la versione 2.0.1 o successive per PHP 7.x.

Esistono due modi per incorporare l'SDK nel tuo progetto:

1. Esegui il comando Packagist per aggiungere l'SDK al file composer.json:

   composer require google/appengine-php-sdk
   

2. Crea manualmente un file composer.json con i seguenti dettagli:

   PHP 7/8

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

In PHP, le API App Engine richiedono la specifica esplicita delle dipendenze. Consulta questo documento per istruzioni su come includere autoload.php.

Importazione delle librerie

Utilizza l'operatore use per importare la classe che ti serve dall'elenco delle API disponibili. Ad esempio, Google\AppEngine\Api\AppIdentity\ClassName può essere importato con la seguente dichiarazione:

use Google\AppEngine\Api\AppIdentity\ClassName;

Considerazioni sulla migrazione

Identità app

Non è necessario apportare modifiche alla configurazione dell'app durante l'upgrade a PHP. Il comportamento, le funzionalità e le istruzioni di configurazione dell'API App Identity rimangono invariati. Per maggiori dettagli, consulta la panoramica dell'API Identity e la guida di riferimento dell'API Identity per le app.

Posta

L'API Mail di PHP rimane per lo più invariata rispetto all'API Mail di PHP 5, con alcune lievi differenze su come attivare e disattivare i servizi di posta. Le sezioni seguenti illustrano le differenze tra i due runtime.

Classe messaggio

In PHP, la classe Message funziona come in PHP 5.5, tranne per il fatto che le importazioni use sono state aggiornate. Le differenze sono le seguenti:

PHP 5.5

use google\appengine\api\mail\Message;

PHP 7/8

use Google\AppEngine\Api\Mail\Message;

Se non riesci a modificare le istruzioni di importazione, l'istruzione di importazione PHP 5.5 originale funzionerà anche per PHP.

Funzione Mail

In PHP 5.5, la funzione PHP nativa mail() è stata sovraccaricata dalla funzione Mail di App Engine.

In PHP, la funzione di posta di App Engine non è più sovraccarica per impostazione predefinita e deve essere abilitata esplicitamente. Questo nuovo comportamento ti consente di riutilizzare la funzione Posta per soddisfare meglio le tue esigenze. Questa modifica ti consente anche di avere visibilità su quale implementazione viene attualmente utilizzata per tutte le chiamate di funzione di posta.

Se preferisci utilizzare la funzione PHP nativa mail() per inviare email utilizzando l'API Mail di App Engine, puoi attivarla nel file php.ini nel seguente modo:

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

Come mostrato nell'esempio precedente, aggiungi l'estensione mailparse per attivare la funzione di posta PHP nativa e imposta la configurazione di runtime sendmail_path sull'implementazione della funzione di posta di App Engine. Dopo aver attivato questa opzione, tutte le chiamate a mail() funzioneranno esattamente come in PHP 5.5.

Per maggiori dettagli, consulta le guide Invio di posta e Ricezione di posta e la guida di riferimento dell'API Mail.

Memcache

Per utilizzare Memcache per PHP, devi aggiungere una dichiarazione esplicita delle librerie Memcache. In precedenza, Memcache per PHP 5.5 non richiedeva una dichiarazione esplicita. Questa dichiarazione esplicita consente di passare in modo flessibile da Memcache PHP nativo a Memcache App Engine.

Le classi PHP Memcache hanno lo stesso comportamento delle classi PHP 5 Memcache, ad eccezione della dichiarazione esplicita. Per ulteriori dettagli, consulta la panoramica di Memcache.

PHP 5.5

Esempio di Memcache per PHP 5.5:

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

Esempio di Memcached per 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

Esempio di API Memcache per PHP:

use Google\AppEngine\Api\Memcache\Memcache;

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

Esempio di API Memcached per 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 preferisci utilizzare il comportamento originale di Memcache per PHP 5 in PHP, puoi continuare a chiamare Memcache in modo implicito includendo alcune righe aggiuntive nel file composer.json. Dopo aver importato il pacchetto appengine-php-sdk da Composer, aggiungi il seguente percorso del file di attivazione all'elemento files nella sezione 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"
    ]
  }
}

Moduli

Non è necessario apportare modifiche alla configurazione dell'app durante l'upgrade a PHP. Il comportamento, le funzionalità e le istruzioni di configurazione dell'API Modules rimangono invariati. Per ulteriori dettagli, consulta la Panoramica dei moduli e la Guida di riferimento dell'API Modules.

Sessione

Sessioni PHP funziona allo stesso modo delle sessioni PHP 5.5. Tuttavia, le istruzioni di configurazione sono diverse perché le sessioni PHP 5.5 utilizzavano la classe MemcacheSessionHandler per impostazione predefinita.

Per utilizzare Sessions for PHP, devi registrare la classe MemcacheSessionHandler con session_set_save_handler() e configurare session.save_path su Memcache. Devi anche attivare Memcache quando accedi alle informazioni di Memcache.

Ad esempio:

PHP 7/8

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

Per ulteriori dettagli, consulta la guida di riferimento dell'API Session.

Coda di attività

Non è necessario apportare modifiche alla configurazione dell'app durante l'upgrade a PHP. Il comportamento, le funzionalità e le istruzioni di configurazione di Task Queue rimangono invariati. Per ulteriori dettagli, consulta la sezione Sessioni della guida Panoramica della coda di attività e la guida di riferimento dell'API Task Queue.

Recupero URL

Per utilizzare URL Fetch per PHP, devi aggiungere una dichiarazione esplicita delle librerie URL Fetch. In precedenza, il servizio URL Fetch per PHP 5 non richiedeva una dichiarazione esplicita e veniva utilizzato implicitamente.

In PHP 5, il servizio URL Fetch di App Engine era l'unico modo per recuperare contenuti internet in PHP 5.5, quindi la maggior parte delle funzioni PHP 5.5 che accedevano a internet sono state corrette per utilizzare automaticamente UrlFetch.

In PHP, la rete PHP nativa può accedere a internet, quindi questa patch automatica non viene eseguita. In alcuni casi, puoi utilizzare il meccanismo UrlFetch originale, in particolare quello che fornisce l'intestazione della richiesta X-Appengine-Inbound-Appid per identificare l'app App Engine che effettua una richiesta alla tua app App Engine.

Per attivare il recupero URL per PHP, puoi utilizzare una dichiarazione esplicita nel wrapper di stream oppure utilizzare direttamente la classe UrlFetch, descritta nelle sezioni seguenti.

Opzione 1a. Gestori di stream

Puoi attivare il servizio di recupero URL di App Engine per effettuare richieste HTTP sia ai gestori di stream PHP http:// sia a quelli https://. Per farlo:

1. Annulla la registrazione del gestore di stream PHP nativo per HTTP(S) utilizzando stream_wrapper_unregister().
2. Registra HTTP(S) nella classe UrlFetchStream utilizzando stream_wrapper_register().
3. Chiama file_get_contents() con la configurazione che vuoi utilizzare per il wrapper di stream.
   • Se vuoi tornare al gestore di stream PHP nativo dal servizio URL Fetch, utilizza stream_wrapper_unregister() e poi registrati utilizzando stream_wrapper_restore().

Per un confronto, vedi gli esempi equivalenti per 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.

Opzione 1b. Intestazioni della risposta HTTP con gestori di stream

Le istruzioni per l'utilizzo delle intestazioni di risposta HTTP(S) con i gestori di stream sono simili a quelle per l'utilizzo dei gestori di stream:

1. Annulla la registrazione del gestore di stream PHP nativo per HTTP(S) utilizzando stream_wrapper_unregister().
2. Registra HTTP(S) nella classe UrlFetchStream utilizzando stream_wrapper_register().
3. Utilizza fopen() anziché file_get_contents() con la configurazione che preferisci.
4. Chiama stream_get_meta_data() ed estrai le informazioni dell'intestazione della risposta indicizzando i metadati per 'wrapper_data. Le intestazioni della risposta vengono restituite in un formato di array simile a quello di $http_response_header in 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");

Opzione 2. Classe UrlFetch

La classe UrlFetch è una classe personalizzata che offre un modo più mirato di utilizzare il servizio di recupero URL per una richiesta HTTP(S) in un ambito più ristretto. A differenza dell'opzione del gestore di stream, la classe UrlFetch non esegue l'override di tutte le richieste HTTP(S) effettuate da funzioni compatibili con i wrapper di stream per utilizzare il servizio URL Fetch. Rispetto all'opzione del gestore di stream, anche la configurazione della classe UrlFetch è più semplice, in quanto non richiede l'utilizzo di varie API PHP, ad esempio:

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

Il seguente esempio di classe UrlFetch è equivalente all'esempio di gestore di 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();

Utenti

Non è necessario apportare modifiche alla configurazione dell'app durante l'upgrade a PHP. Il comportamento, le funzionalità e le istruzioni di configurazione dell'API Users rimangono invariati. Per ulteriori dettagli, consulta la panoramica dell'API Users e la guida di riferimento dell'API Users.

Librerie create dalla community

Quando esegui l'upgrade a PHP, puoi utilizzare l'API con il contributo della community per datastore.

Altre considerazioni

• Per testare la funzionalità dei servizi in bundle legacy nella tua app PHP, puoi utilizzare il server di sviluppo locale. Quando esegui il comando dev_appserver.py, imposta l'argomento --php_executable_path su un eseguibile PHP. Tieni presente che è diverso da PHP 5, che richiede un eseguibile php-cgi.

  Se il progetto ha un file composer.json, imposta --php-composer-path sul percorso del file composer.phar.

• Per eseguire il deployment dell'app, utilizza il comando gcloud app deploy.

• Il logging nel runtime PHP segue lo standard di logging in Cloud Logging. Nel runtime PHP, i log delle app non sono più raggruppati con i log delle richieste, ma sono separati in record diversi. Per saperne di più sulla lettura e la scrittura dei log, consulta la guida alla scrittura e alla visualizzazione dei log.

Esempi

Per visualizzare esempi di come utilizzare i servizi raggruppati legacy con PHP, scarica gli esempi di codice.