Accéder aux anciens services groupés pour PHP

Cette page explique comment installer et utiliser les services groupés avec l'environnement d'exécution PHP dans l'environnement standard App Engine. Votre application peut accéder aux services groupés via le SDK des services App Engine pour PHP.

Avant de commencer

Consultez la liste des API des anciens services groupés que vous pouvez appeler dans l'environnement d'exécution PHP.
Mettez à jour votre fichier app.yaml pour inclure la ligne suivante :
```
app_engine_apis: true
```
Pour tester votre application PHP, vous devez la déployer à l'aide de gcloud app deploy.

Installer le SDK App Engine pour PHP

Le SDK App Engine pour PHP est disponible sur GitHub à l'adresse appengine-php-sdk. Vous devez utiliser la version 2.1 ou ultérieure pour PHP 8.1 et versions ultérieures, et la version 2.0.1 ou ultérieure pour PHP 7.x.

Il existe deux manières d'intégrer le SDK à votre projet :

Exécutez la commande Packagist pour ajouter le SDK à votre fichier composer.json :
```
composer require google/appengine-php-sdk
```

Créez manuellement un fichier composer.json avec les informations suivantes :

PHP 7/8

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

Dans PHP, les API App Engine nécessitent une spécification explicite des dépendances. Consultez cette documentation pour savoir comment inclure autoload.php.

Importer les bibliothèques

Utilisez l'opérateur use pour importer la classe dont vous avez besoin dans la liste des API disponibles. Par exemple, vous pouvez importer Google\AppEngine\Api\AppIdentity\ClassName avec l'instruction suivante :

use Google\AppEngine\Api\AppIdentity\ClassName;

Considérations sur la migration

Identité de l'application

Vous n'avez pas besoin de modifier la configuration de votre application lorsque vous passez à PHP. Le comportement, les fonctionnalités et les instructions de configuration de l'API App Identity restent inchangés. Pour en savoir plus, consultez la Présentation de l'API App Identity et le guide de référence de l'API App Identity.

Mail (Messagerie)

L'API Mail de PHP reste essentiellement la même que l'API Mail de PHP 5, avec quelques légères différences sur la façon d'activer et de désactiver les services Mail. Les sections suivantes décrivent les différences entre les deux environnements d'exécution.

Classe de messages

Dans PHP, la classe Message fonctionne de la même manière que dans PHP 5.5, à la différence que les importations use ont été modifiées. Les différences sont les suivantes :

PHP 5.5

use google\appengine\api\mail\Message;

PHP 7/8

use Google\AppEngine\Api\Mail\Message;

Si vous ne parvenez pas à modifier les instructions d'importation, l'instruction d'importation PHP 5.5 d'origine fonctionne également pour PHP.

Fonction de messagerie

Dans PHP 5.5, la fonction PHP mail() native était surchargée par la fonction de messagerie d'App Engine.

Dans PHP, la fonction de messagerie d'App Engine n'est plus surchargée par défaut et doit être explicitement activée. Ce nouveau comportement vous permet de réutiliser la fonction de messagerie pour mieux répondre à vos besoins. Cette modification vous permet également de disposer d'une visibilité sur la mise en œuvre actuellement utilisée pour tous les appels de la fonction de messagerie.

Si vous préférez utiliser la fonction PHP mail() native pour envoyer des messages à l'aide de l'API App Engine Mail, vous pouvez l'activer dans votre fichier php.ini comme suit :

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

Comme indiqué dans l'exemple précédent, ajoutez l'extension mailparse pour activer la fonction de messagerie PHP native et définissez la configuration de l'environnement d'exécution sendmail_path sur l'implémentation de la fonction de messagerie d'App Engine. Après avoir activé cette méthode, tous les appels à mail() fonctionneront exactement comme dans PHP 5.5.

Pour en savoir plus, consultez les guides Envoyer des e-mails et Recevoir des e-mails, ainsi que le guide de référence de l'API Mail.

Memcache

Pour utiliser Memcache pour PHP, vous devez ajouter une déclaration explicite des bibliothèques Memcache. Auparavant, Memcache pour PHP 5.5 ne nécessitait pas de déclaration explicite. Cette déclaration explicite permet de basculer entre le système Memcache PHP natif et le service Memcache d'App Engine.

Les classes Memcache PHP ont le même comportement que les classes Memcache PHP 5, à l'exception de la déclaration explicite. Pour en savoir plus, consultez la Présentation de Memcache.

PHP 5.5

Exemple de Memcache pour PHP 5.5 :

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

Exemple avec Memcached pour 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

Exemple avec l'API Memcache pour PHP :

use Google\AppEngine\Api\Memcache\Memcache;

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

Exemple avec l'API Memcached pour 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(),
]);

Si vous préférez utiliser le comportement d'origine de Memcache pour PHP 5 dans PHP, vous pouvez continuer à appeler Memcache implicitement en incluant quelques lignes supplémentaires dans votre fichier composer.json. Après avoir importé le package appengine-php-sdk à partir de Composer, ajoutez le chemin d'accès de fichier d'activation suivant à l'élément files dans la section 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"
    ]
  }
}

Modules

Vous n'avez pas besoin de modifier la configuration de votre application lorsque vous passez à PHP. Le comportement, les fonctionnalités et les instructions de configuration de l'API Modules restent les mêmes. Pour en savoir plus, consultez la Présentation des modules et le Guide de référence de l'API Modules.

Session

Les sessions PHP fonctionnent de la même manière que les sessions PHP 5.5. Cependant, les instructions de configuration diffèrent, car les sessions PHP 5.5 utilisaient par défaut la classe MemcacheSessionHandler.

Pour utiliser des sessions pour PHP, vous devez enregistrer la classe MemcacheSessionHandler avec session_set_save_handler() et configurer session.save_path sur Memcache. Vous devez également activer Memcache lorsque vous accédez aux informations Memcache.

Exemple :

PHP 7/8

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

Pour en savoir plus, consultez le guide de référence de l'API Session.

File d'attente de tâches

Vous n'avez pas besoin de modifier la configuration de votre application lorsque vous passez à PHP. Le comportement, les fonctionnalités et les instructions de configuration pour la file d'attente de tâches restent inchangés. Reportez-vous à la section "Sessions" du guide Présentation des files d'attente de tâches et du guide de référence de l'API Task Queue pour en savoir plus.

URL Fetch

Pour utiliser URL Fetch pour PHP, vous devez ajouter une déclaration explicite des bibliothèques URL Fetch. Auparavant, le service de récupération d'URL pour PHP 5 ne bénéficiait pas d'une déclaration explicite et était utilisé implicitement.

Dans PHP 5, le service de récupération d'URL d'App Engine était le seul moyen de récupérer le contenu Internet dans PHP 5.5. Par conséquent, la plupart des fonctions PHP 5.5 qui ont accédé à Internet ont été corrigées pour utiliser automatiquement UrlFetch.

Dans PHP, la mise en réseau PHP native peut accéder à Internet. Cette correction automatique n'est donc pas effectuée. Dans certains cas, vous pouvez utiliser le mécanisme UrlFetch d'origine, en particulier le mécanisme qui fournit l'en-tête de requête X-Appengine-Inbound-Appid pour identifier l'application App Engine. qui envoie une requête à votre application App Engine.

Pour activer le service de récupération d'URL pour PHP, vous pouvez utiliser une déclaration explicite dans le wrapper de flux ou utiliser directement la classe UrlFetch, comme décrit dans les sections suivantes.

Option 1a. Gestionnaires de flux

Vous pouvez activer le service de récupération d'URL d'App Engine pour envoyer des requêtes HTTP aux gestionnaires de flux PHP http:// et https://. Procédez comme suit :

Annulez l'enregistrement du gestionnaire de flux PHP natif pour HTTP(S) à l'aide de stream_wrapper_unregister().
Enregistrez HTTP(S) dans la classe UrlFetchStream à l'aide de stream_wrapper_register().
Appelez file_get_contents() avec la configuration que vous souhaitez utiliser pour le wrapper de flux.
- Si vous souhaitez revenir au gestionnaire de flux PHP natif à partir du service de récupération d'URL, utilisez stream_wrapper_unregister(), puis enregistrez-vous à l'aide de stream_wrapper_restore().

À titre de comparaison, consultez les exemples équivalents pour PHP 5 et 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.

Option 1b. En-têtes de réponse HTTP avec des gestionnaires de flux

Les instructions d'utilisation des en-têtes de réponse HTTP(S) avec des gestionnaires de flux sont similaires aux instructions d'utilisation des gestionnaires de flux :

Annulez l'enregistrement du gestionnaire de flux PHP natif pour HTTP(S) à l'aide de stream_wrapper_unregister().
Enregistrez HTTP(S) dans la classe UrlFetchStream à l'aide de stream_wrapper_register().
Utilisez fopen() au lieu de file_get_contents() avec la configuration souhaitée.
Appelez stream_get_meta_data() et extrayez les informations de l'en-tête de réponse en indexant les métadonnées pour 'wrapper_data. Les en-têtes de réponse sont renvoyés sous forme de tableau semblable à celui de $http_response_header dans 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");

Option 2. Classe UrlFetch

La classe UrlFetch est une classe personnalisée qui permet d'utiliser le service de récupération d'URL pour une requête HTTP(S) de manière plus ciblée selon un champ d'application plus petit. Contrairement à l'option "Gestionnaire de flux", la classe UrlFetch ne remplace pas toutes les requêtes HTTP(S) effectuées à partir de fonctions compatibles avec le wrapper de flux pour utiliser le service de récupération d'URL. Par rapport à l'option du gestionnaire de flux, la configuration de la classe UrlFetch est également plus simple, car elle ne nécessite pas l'utilisation de diverses API PHP telles que :

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

L'exemple de classe UrlFetch suivant est équivalent à l'exemple du gestionnaire de flux :

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

Utilisateurs

Vous n'avez pas besoin de modifier la configuration de votre application lorsque vous passez à PHP. Le comportement, les fonctionnalités et les instructions de configuration de l'API Users restent identiques. Pour en savoir plus, consultez la présentation de l'API Users et le guide de référence de l'API Users.

Bibliothèques issues de la communauté

Vous pouvez utiliser l'API fournie par la communauté pour datastore lors de la mise à niveau vers PHP.

Autres points à noter

Pour tester la fonctionnalité des anciens services groupés dans votre application PHP, vous pouvez utiliser le serveur de développement local. Lors de l'exécution de la commande dev_appserver.py, définissez l'argument --php_executable_path sur un exécutable PHP. Notez que cela diffère de PHP 5, qui nécessite un exécutable php-cgi.

Si le projet contient un fichier composer.json, définissez --php-composer-path sur le chemin d'accès du fichier composer.phar.
Pour déployer votre application, utilisez la commande gcloud app deploy.
La journalisation dans l'environnement d'exécution PHP suit la norme de journalisation dans Cloud Logging. Dans l'environnement d'exécution PHP, les journaux d'application ne sont plus regroupés avec les journaux de requêtes, mais sont séparés dans des enregistrements distincts. Pour en savoir plus sur la lecture et l'écriture des journaux, consultez le guide Écrire et afficher des journaux.

Exemples

Pour obtenir des exemples d'utilisation des anciens services groupés avec PHP, téléchargez les exemples de code.