Accesso ai servizi in bundle legacy per PHP 7/8

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

Prima di iniziare

Consulta l'elenco delle API dei servizi in bundle legacy che puoi chiamare nel runtime PHP 7/8.
Aggiorna il file app.yaml in modo da includere la seguente riga:
```
app_engine_apis: true
```
Per testare la tua app PHP 7/8, devi eseguirne il deployment utilizzando gcloud app deploy.

Installazione dell'SDK di App Engine per PHP

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

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

Esegui il comando Packagist per aggiungere l'SDK al file composer.json:
```
composer require google/appengine-php-sdk
```

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 7/8, le API App Engine richiedono una 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 l'istruzione:

use Google\AppEngine\Api\AppIdentity\ClassName;

Considerazioni sulla migrazione

Identità app

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

Mail

L'API Mail di PHP 7/8 rimane per lo più uguale all'API Mail di PHP 5, con alcune piccole differenze nell'attivazione e nella disattivazione dei servizi di posta. Le sezioni seguenti illustrano le differenze tra i due runtime.

Classe messaggio

In PHP 7/8, la classe Message funziona come in PHP 5.5, ad eccezione del 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 originale di PHP 5.5 funzionerà anche per PHP 7/8.

Funzione di posta

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

In PHP 7/8, la funzione di posta di App Engine non è più sovraccaricata per impostazione predefinita e deve essere abilitata esplicitamente. Questo nuovo comportamento consente di riutilizzare la funzione Mail per adattarla meglio alle proprie esigenze. Questa modifica consente inoltre di avere visibilità sull'implementazione attualmente in uso per tutte le chiamate a funzione di posta.

Se preferisci utilizzare la funzione PHP nativa mail() per inviare la posta mediante l'API Mail di App Engine, puoi abilitarla 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 abilitato questa opzione, tutte le chiamate a mail() funzioneranno esattamente come in PHP 5.5.

Fai riferimento alle guide Invio di posta e Ricezione della posta e alla guida di riferimento dell'API Mail per ulteriori dettagli.

Memcache

Per utilizzare Memcache per PHP 7/8, devi aggiungere una dichiarazione esplicita delle librerie Memcache. In precedenza, Memcache per PHP 5.5 non richiedeva una dichiarazione esplicita. Questa dichiarazione esplicita consente la flessibilità di passare dalla memcache PHP nativa a quella di App Engine.

Le classi Memcache PHP 7/8 hanno lo stesso comportamento delle classi Memcache PHP, ad eccezione della dichiarazione esplicita. Per ulteriori dettagli, consulta la panoramica su 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 7/8:

use Google\AppEngine\Api\Memcache\Memcache;

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

Esempio di API Memcached per PHP 7/8:

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 7/8, puoi continuare a chiamare Memcache in modo implicito includendo qualche altra riga 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 quando esegui l'upgrade a PHP 7/8. Il comportamento, le funzionalità e le istruzioni di configurazione per l'API Modules rimangono invariati. Per ulteriori dettagli, consulta la Panoramica dei moduli e la Guida di riferimento dell'API Moduli.

Session

Le sessioni PHP 7/8 funzionano come le 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 la funzionalità Sessioni per PHP 7/8, devi registrare la classe MemcacheSessionHandler con session_set_save_handler() e configurare session.save_path su Memcache. Devi inoltre 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 API Session.

Coda di attività

Non è necessario apportare modifiche alla configurazione dell'app quando esegui l'upgrade a PHP 7/8. Il comportamento, le funzionalità e le istruzioni di configurazione per la coda di attività rimangono invariati. Per ulteriori dettagli, consulta la sezione Sessioni della guida Panoramica delle code di attività e la guida di riferimento dell'API Tasks Queue.

Recupero URL

Per utilizzare il recupero URL per PHP 7/8, devi aggiungere una dichiarazione esplicita delle librerie URL Fetch. In precedenza, il servizio di recupero URL per PHP 5 non richiedeva una dichiarazione esplicita ed veniva utilizzato in modo implicito.

In PHP 5, il servizio di recupero URL di App Engine era l'unico modo per recuperare i contenuti internet in PHP 5.5, di conseguenza alla maggior parte delle funzioni di PHP 5.5 che accedevano a internet è stata applicata la patch per utilizzare UrlFetch automaticamente.

In PHP 7/8, le reti PHP native possono accedere a Internet, perciò l'applicazione automatica non viene eseguita. In alcuni casi, puoi utilizzare il meccanismo UrlFetch originale, in particolare il meccanismo 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 abilitare il recupero degli URL per PHP 7/8, puoi utilizzare una dichiarazione esplicita nel wrapper del flusso oppure utilizzare direttamente la classe UrlFetch, descritta nelle seguenti sezioni.

Opzione 1a. Gestori degli stream

Puoi abilitare il servizio di recupero URL di App Engine per effettuare richieste HTTP ai gestori di stream PHP http:// e https://. Per farlo:

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

Per un confronto, vedi gli esempi equivalenti per PHP 5 e PHP 7/8:

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 delle risposte HTTP con gestori di flussi

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

Annulla la registrazione del gestore di stream PHP nativo per HTTP(S) utilizzando stream_wrapper_unregister().
Registra HTTP(S) nella UrlFetchStreamclasse utilizzando stream_wrapper_register().
Utilizza fopen() anziché file_get_contents() con la configurazione che preferisci.
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 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 fornisce un modo più mirato per utilizzare il servizio di recupero URL per una richiesta HTTP(S) in un ambito più ristretto. A differenza dell'opzione del gestore dei flussi, la classe UrlFetch non sostituisce tutte le richieste HTTP(S) effettuate da funzioni compatibili con il wrapper dei flussi per utilizzare il servizio di recupero URL. Rispetto all'opzione del gestore dei flussi, anche la configurazione della classe UrlFetch è più semplice, in quanto non richiede l'uso di varie API PHP quali:

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 quando esegui l'upgrade a PHP 7/8. Il comportamento, le funzionalità e le istruzioni di configurazione per l'API Users rimangono invariati. Per ulteriori dettagli, consulta la panoramica sull'API Users e la guida di riferimento dell'API Users.

Librerie fornite dalla community

Puoi utilizzare l'API fornita dalla community per datastore quando esegui l'upgrade a PHP 7/8.

Altre considerazioni

Per testare la funzionalità dei servizi in bundle legacy nell'app PHP 7/8, puoi utilizzare il server di sviluppo locale. Quando esegui il comando dev_appserver.py, imposta l'argomento --php_executable_path su un file eseguibile PHP 7/8. Tieni presente che è diverso da PHP 5, che richiede un file 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 della tua app, utilizza il comando gcloud app deploy.
Il logging nel runtime PHP 7/8 segue lo standard di logging in Cloud Logging. Nel runtime PHP 7/8, i log delle app non sono più in bundle con i log delle richieste, ma sono separati in record diversi. Per ulteriori informazioni sulla lettura e sulla scrittura dei log, consulta la guida relativa alla scrittura e alla visualizzazione dei log.

Esempi

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