Environnement d'exécution PHP

L'environnement d'exécution PHP est la pile logicielle chargée d'installer le code de votre service Web et ses dépendances, et d'exécuter votre service.

Pour spécifier PHP pour l'environnement standard App Engine, déclarez l'environnement d'exécution dans le fichier app.yaml. Par exemple :

runtime: phpVERSION

Où VERSION correspond aux numéros de version PHP MAJOR et MINOR. Par exemple, pour utiliser la dernière version de PHP, PHP 8.3, spécifiez 83.

Pour les autres versions de PHP compatibles, ainsi que pour la version d'Ubuntu correspondante pour votre version de PHP, consultez la page Calendrier de compatibilité des environnements d'exécution.

Version de PHP

L'environnement d'exécution PHP utilise la dernière version stable de la version spécifiée dans le fichier app.yaml. App Engine se met automatiquement à jour en cas de nouvelle version corrective, mais pas en cas de nouvelle version mineure.

Par exemple, l'application peut être déployée sur PHP 7.3.0 et faire ultérieurement l'objet d'une mise à jour automatique vers la version 7.3.1, mais elle ne sera pas automatiquement mise à jour vers PHP 7.4.0.

Démarrage de l'application

Vous devrez déployer un contrôleur frontal pour gérer le routage de toutes les requêtes.

Les exemples suivants présentent différentes manières de diffuser votre application :

Si votre application contient un fichier public/index.php ou index.php, App Engine utilise ce fichier pour diffuser l'application.

Nous vous recommandons d'utiliser un framework, tel que Laravel, Symfony ou Slim, car il fournit un routage léger pour l'écriture et le déploiement rapide d'applications PHP. Consultez un exemple de contrôleur frontal Slim.

Toutefois, si vous migrez une ancienne application, consultez l'exemple de fichier index.php suivant pour importer les fichiers PHP dont vous avez besoin et mettre en œuvre le contrôleur frontal manuellement :
```
switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
    case '/':
        require 'homepage.php';
        break;
    case '/contact.php':
        require 'contact.php';
        break;
    default:
        http_response_code(404);
        exit('Not Found');
}
```
Si vous spécifiez l'élément entrypoint facultatif dans votre fichier app.yaml, App Engine utilise la commande de l'élément entrypoint pour diffuser votre application à la place de public/index.php ou index.php :
```
    entrypoint: serve path/to/my/front/controller.php
```
Le champ entrypoint utilise la commande serve intégrée, qui est un programme de l'environnement d'exécution PHP. Ce programme commence l'implémentation de php-fpm et démarre un serveur Web en arrière-plan. Ce serveur Web achemine tout le trafic vers le fichier PHP fourni en utilisant le modèle de conception du contrôleur frontal.

La commande serve comporte deux options facultatives :
- --workers=N : spécifie le nombre N de nœuds de calcul php-fpm. Si vous ne définissez pas l'option --workers, la commande serve devine le nombre de nœuds de calcul en fonction de la quantité de mémoire disponible. Pour de meilleurs résultats, définissez les valeurs de l'option --workers de la commande serve et de l'élément max_concurrent_requests sur le même nombre.
- --enable-dynamic-workers : indique que vous souhaitez que les nœuds de calcul php-fpm soient générés uniquement en fonction des besoins. Une règle statique est utilisée par défaut pour les nœuds de calcul php-fpm. Vous pouvez modifier le nombre maximal de nœuds de calcul générés à l'aide de l'option --workers=N. Par défaut, le nombre maximal de nœuds de calcul générés correspond à celui défini par la stratégie statique.
Les options facultatives doivent se situer avant le chemin d'accès au contrôleur frontal :
```
    entrypoint: serve --workers=2 --enable-dynamic-workers path/to/index.php
```
Vous pouvez déployer un processus de nœud de calcul de longue durée en définissant l'élément entrypoint dans le chemin de fichier du processus de nœud de calcul :
```
    entrypoint: php long-running-worker-file.php
```
Si l'élément entrypoint exécute un script avec un processus de longue durée, tel qu'un nœud de calcul Pub/Sub abonné à un sujet, n'utilisez pas la commande serve.

Pour en savoir plus, consultez la documentation de référence sur app.yaml.

Extensions activées

Les extensions suivantes ont été activées dans l'environnement d'exécution PHP pour App Engine :

BCMath
bz2
Calendar
core
cgi
ctype
cURL
date
dba
dom
enchant
Exif
fcgi
fileinfo
filter
FTP
GD
gettext
GMP
hash
iconv
intl
json
LDAP
libxml
mbstring
MYSQLi
mysqlnd
MySQL (PDO)
OPcache
OpenSSL
PCNTL
pcre
PDO
pgsql
Phar
posix
PostgreSQL (PDO)
Reflection
session
Shmop
SimpleXML
SOAP
Sockets
sodium (PHP 8.x only, not available for PHP 7.x)
SPL
SQLite (PDO)
SQLite3
standard
test
tidy
tokenizer
XML
XMLreader
XMLrpc (PHP 7.x only, not available for PHP 8.x)
XMLwriter
XSL
zend
Zip
Zlib

Extensions à chargement dynamique

Les extensions suivantes peuvent être chargées dynamiquement via la configuration du fichier php.ini :

Pour activer ces extensions, ajoutez-leur des instructions dans votre fichier php.ini sous extension, comme suit :

extension=memcached.so
extension=grpc.so
extension=protobuf.so
extension=mongodb.so
extension=imagick.so
extension=opencensus.so
extension=redis.so

[opentelemetry]
extension=opentelemetry.so

Variables d'environnement

Les variables d'environnement suivantes sont définies par l'environnement d'exécution :

Variable d'environnement	Description
`GAE_APPLICATION`	ID de votre application App Engine. Cet ID est précédé du préfixe "`region code`~", tel que "e~" pour les applications déployées en Europe.
`GAE_DEPLOYMENT_ID`	ID du déploiement actuel.
`GAE_ENV`	Environnement App Engine. Variable définie sur `standard`.
`GAE_INSTANCE`	ID de l'instance sur laquelle votre service est en cours d'exécution.
`GAE_MEMORY_MB`	Quantité de mémoire disponible pour le processus d'application, en Mo.
`GAE_RUNTIME`	Environnement d'exécution spécifié dans le fichier `app.yaml`.
`GAE_SERVICE`	Nom de service spécifié dans le fichier `app.yaml`. Si aucun nom de service n'est spécifié, il est défini par défaut sur `default`.
`GAE_VERSION`	Libellé de la version actuelle du service.
`GOOGLE_CLOUD_PROJECT`	ID du projet Google Cloud associé à votre application.
`PORT`	Port qui reçoit les requêtes HTTP.
`NODE_ENV` (disponible uniquement dans l'environnement d'exécution Node.js)	Variable définie sur `production` lorsque votre service est déployé.

Vous pouvez définir des variables d'environnement supplémentaires dans le fichier app.yaml, mais les valeurs ci-dessus ne peuvent pas être remplacées, sauf NODE_ENV.

HTTPS et proxy de transfert

App Engine met fin aux connexions HTTPS au niveau de l'équilibreur de charge et transfère les requêtes à votre application. Certaines applications doivent déterminer l'adresse IP et le protocole de la requête d'origine. L'adresse IP de l'utilisateur est disponible dans l'en-tête standard X-Forwarded-For. Les applications nécessitant ces informations doivent configurer leur framework Web pour qu'il fasse confiance au proxy.

Système de fichiers

L'environnement d'exécution comprend un répertoire /tmp accessible en écriture, tous les autres répertoires ayant un accès en lecture seule. Le fait d'écrire des données dans /tmp utilise la mémoire système. Pour en savoir plus, consultez la section Disponibilité de tempnam() et sys_get_temp_dir().

Serveur de métadonnées

Chaque instance de votre application peut demander des informations sur l'instance et votre projet à l'aide du serveur de métadonnées App Engine.

Vous pouvez accéder au serveur de métadonnées via les points de terminaison suivants :

http://metadata
http://metadata.google.internal

Les requêtes envoyées au serveur de métadonnées doivent inclure l'en-tête de requête Metadata-Flavor: Google. Cet en-tête indique que la requête a été envoyée dans le but de récupérer les valeurs de métadonnées.

La table suivante répertorie les points de terminaison sur lesquels vous pouvez effectuer des requêtes HTTP pour des métadonnées spécifiques :

Point de terminaison des métadonnées	Description
`/computeMetadata/v1/project/numeric-project-id`	Numéro de projet attribué à votre projet.
`/computeMetadata/v1/project/project-id`	ID de projet attribué à votre projet.
`/computeMetadata/v1/instance/region`	Région dans laquelle l'instance est en cours d'exécution.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	Adresse e-mail du compte de service par défaut attribué à votre projet.
`/computeMetadata/v1/instance/service-accounts/default/`	Répertorie tous les comptes de service par défaut pour votre projet.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	Répertorie tous les champs d'application disponibles pour les comptes de service par défaut.
`/computeMetadata/v1/instance/service-accounts/default/token`	Renvoie le jeton d'authentification pouvant servir à authentifier votre application auprès d'autres API Google Cloud.

Par exemple, pour récupérer votre ID de projet, envoyez une requête à http://metadata.google.internal/computeMetadata/v1/project/project-id.

Vous trouverez ci-dessous un exemple décrivant comment appeler les points de terminaison des métadonnées à l'aide de cURL ou de la bibliothèque cliente Google Cloud :

/**
 * Requests a key from the Metadata server using the Google Cloud SDK. Install
 * the Google Cloud SDK by running "composer install google/cloud"
 *
 * @param $metadataKey the key for the metadata server
 */
function request_metadata_using_google_cloud($metadataKey)
{
    $metadata = new Google\Cloud\Core\Compute\Metadata();
    $metadataValue = $metadata->get($metadataKey);

    return $metadataValue;
}

/**
 * Requests a key from the Metadata server using cURL.
 *
 * @param $metadataKey the key for the metadata server
 */
function request_metadata_using_curl($metadataKey)
{
    $url = 'http://metadata/computeMetadata/v1/' . $metadataKey;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Metadata-Flavor: Google'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    return curl_exec($ch);
}

Sessions

PHP propose une couche de gestion des sessions qui permet aux applications Web de préserver les informations relatives à l'état d'un compte utilisateur entre les requêtes. Les sessions au sein d'App Engine fonctionnent comme des sessions dans toute autre application PHP.

Pour définir une variable dans une session utilisateur, vous pouvez utiliser le code suivant :

session_start();
$_SESSION['Foo'] = 'Bar';

Le code suivant imprimera Bar lors d'une requête ultérieure par le même utilisateur :

session_start();
print $_SESSION['Foo']; // prints Bar

Pour les sessions plus longues, utilisez un autre service de stockage tel que Cloud SQL.

Clés $_SERVER spéciales

PHP rend le tableau $_SERVER[] spécial disponible dans le champ d'application de la requête. En plus des paramètres CGI standards, App Engine propose quelques clés supplémentaires utiles :

GAE_APPLICATION : ID du projet Google Cloud de l'application actuelle.
GAE_DEPLOYMENT_ID : ID du code source déployé.
GAE_ENV : environnement App Engine (standard ou flexible) dans lequel votre application s'exécute.
GAE_INSTANCE : nom de l'instance en cours d'exécution.
GAE_MEMORY_MB : quantité de mémoire disponible pour le processus d'application, en Mo.
GAE_RUNTIME : environnement d'exécution spécifié dans le fichier app.yaml, tel que php72.
GAE_SERVICE : nom du service actuellement déployé.
GAE_VERSION : nom de la version actuellement déployée.
GOOGLE_CLOUD_PROJECT : ID du projet Google Cloud.
HTTP_X_APPENGINE_CITY : nom de la ville d'origine de la requête. Par exemple, la valeur d'en-tête d'une requête provenant de Mountain View serait "mountain view".
HTTP_X_APPENGINE_CITYLATLONG : latitude et longitude de la ville d'origine de la requête. Cette chaîne peut par exemple prendre la forme "37.386051, -122.083851" pour une requête provenant de Mountain View.
HTTP_X_APPENGINE_COUNTRY : pays d'origine de la requête, sous forme de code de pays ISO 3166-1 alpha-2. App Engine définit ce code à partir de l'adresse IP du client.
HTTP_X_APPENGINE_HTTPS : vérifie l'utilisation du protocole HTTPS.
HTTP_X_APPENGINE_REGION : nom de la région d'origine de la requête. Cette valeur n'a de sens que dans le contexte du pays dans X-Appengine-Country. Par exemple, si le pays est "États-Unis" et la région est "ca", ce "ca" signifie "Californie", et non Canada.
HTTP_X_APPENGINE_USER_IP : adresse IP du client. Notez que $_SERVER['HTTP_X_APPENGINE_USER_IP'] est la seule manière permettant à votre application de récupérer l'adresse IP du client. La variable $_SERVER['REMOTE_ADDR'] n'est pas disponible dans App Engine.

Directives avec de nouveaux paramètres d'initialisation par défaut

Le tableau suivant spécifie les directives dont les valeurs d'initialisation par défaut diffèrent de celles fournies avec l'interpréteur PHP standard disponible sur php.net. Pour trouver les valeurs par défaut des directives non spécifiées dans le tableau suivant, reportez-vous aux directives php.ini.

Directive	Valeur par défaut dans App Engine
`expose_php`	`Off`
`memory_limit`	`-1`
`max_execution_time`	`0`
`error_reporting`	`E_ALL & ~E_DEPRECATED & ~E_STRICT`
`display_errors`	`Off`
`display_startup_errors`	`Off`
`log_errors`	`On`
`log_errors_max_len`	`0`
`ignore_repeated_errors`	`Off`
`ignore_repeated_source`	`Off`
`html_errors`	`Off`
`opcache.enable`	`On`
`opcache.validate_timestamps`	`Off`
`opcache.memory_consumption`	`32`

Remplacez ces instructions par défaut en les incluant dans un fichier php.ini pour votre application.

Disponibilité de `tempnam()` et `sys_get_temp_dir()`

Les applications App Engine s'exécutent dans un bac à sable de sécurité où seul le répertoire /tmp est accessible en écriture et stocké dans la mémoire RAM de l'instance. Pour cette raison, la version de tempnam() d'App Engine renvoie un fichier temporaire en mémoire pouvant être écrit ultérieurement sur une solution de stockage permanent, telle que les buckets Cloud Storage.

Voici un exemple d'écriture dans le fichier temporaire en mémoire à l'aide de file_put_contents() et fwrite().

<?php
$dir = sys_get_temp_dir();
$tmp = tempnam($dir, "foo");
file_put_contents($tmp, "hello");
$f = fopen($tmp, "a");
fwrite($f, " world");
fclose($f);
echo file_get_contents($tmp);

Le résultat attendu de l'exemple serait le suivant :

hello world

Gérer des dépendances avec l'outil Composer

Pour en savoir plus, consultez la page Spécifier des dépendances.