Environnement d'exécution PHP

L'environnement d'exécution PHP est la pile logicielle chargée d'installer le code et les dépendances de votre application, puis d'exécuter cette application dans l'environnement flexible.

Versions de PHP

PHP 8.3 utilise des buildpacks. Pour obtenir la liste complète des versions de PHP compatibles, ainsi que la version d'Ubuntu correspondante, consultez la page Programmation de la compatibilité avec l'environnement d'exécution.

Pour utiliser une version compatible de PHP, vous devez effectuer les opérations suivantes :

  • Installez gcloud CLI version 420.0.0 ou ultérieure. Vous pouvez mettre à jour les outils de la CLI en exécutant la commande gcloud components update. Pour afficher la version installée, vous pouvez exécuter la commande gcloud version.

  • Incluez les paramètres runtime_config et operating_system dans votre fichier app.yaml pour spécifier un système d'exploitation.

  • Déclarez la racine du document pour votre application dans le fichier app.yaml :

      runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: "web"

    Bien que vous puissiez spécifier le répertoire racine du projet (.) comme racine du document, nous vous recommandons d'utiliser un sous-répertoire pour le paramètre document_root.

    Le code source se trouve dans le répertoire /workspace au lieu du répertoire racine (/). Si vous remplacez une configuration, les processus NGINX ou supervisor référencent votre fichier de configuration dans ce répertoire. Pour mettre à jour les références correspondantes, procédez comme suit :

    • Modifiez les instructions include de votre configuration NGINX pour qu'elles soient relatives à /workspace au lieu de /etc/nginx.

    • Certains fichiers, tels que gzip_params, ne sont pas inclus. Pour référencer ces fichiers, incluez les vôtres ou copiez-les à partir de GitHub. Les fichiers tels que mime.types et fastcgi_params sont disponibles dans le répertoire /etc/nginx.

    • Certains modules NGINX, tels que nginx-plus-module-ndk, ne sont pas installés. Définissez la valeur $docroot ou ajoutez-la manuellement dans votre fichier de configuration NGINX.

  • Vous pouvez éventuellement spécifier une version d'exécution :

    • Incluez le paramètre runtime_version dans votre app.yaml. Par défaut, la dernière version de PHP est utilisée si le paramètre runtime_version n'est pas spécifié.

      • Pour spécifier PHP 8.3 sur Ubuntu 22 :

        runtime: php
env: flex

runtime_config:
    operating_system: "ubuntu22"
    runtime_version: "8.3"
    document_root: .

      • Pour spécifier la dernière version compatible de PHP sur Ubuntu 22, procédez comme suit :

          runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: .

    • Incluez une version de PHP dans le fichier composer.json.

      {
    "require": {
        "php": "8.3.*"
    }
}

    Pour plus d'informations, consultez la documentation de référence du fichier app.yaml.

Versions précédentes de l'environnement d'exécution

Pour utiliser PHP version 7.3 et antérieure, procédez comme suit :

  • Déclarez la racine du document pour votre application. Vous pouvez effectuer cette opération dans le fichier app.yaml :

    runtime: php
env: flex
api_version: 1

runtime_config:
  document_root: .

    Bien que vous puissiez spécifier le répertoire racine du projet (.) comme racine du document, nous vous recommandons d'utiliser un sous-répertoire pour le paramètre document_root.

  • Spécifiez une version de PHP dans le fichier composer.json pour éviter que votre application ne soit automatiquement mise à niveau lorsqu'une nouvelle version de PHP devient disponible.

    {
    "require": {
        "php": "7.3.*"
    }
}

Compatibilité avec d'autres environnements d'exécution PHP

Si vous devez utiliser une version de PHP non compatible, vous pouvez créer un environnement d'exécution personnalisé et sélectionner une image de base valide avec la version de PHP dont vous avez besoin.

Pour les images de base fournies par Google ou les images de base PHP Docker, consultez la section Créer des environnements d'exécution personnalisés.

Personnaliser NGINX

Pour définir un fichier de configuration personnalisé, créez le fichier nginx-app.conf dans le répertoire racine de votre projet.

Par défaut, le contrôleur frontal du framework utilise le fichier index.php. Vous devrez peut-être modifier cette configuration en fonction de votre projet. Par exemple, le framework Symfony utilise app.php au lieu de index.php. Vous pouvez modifier le nom du fichier dans la section runtime_config de votre fichier app.yaml :

runtime: php
env: flex

runtime_config:
  operating_system: "ubuntu22"
  document_root: .
  front_controller_file: app.php

Pour la version 7.3 et antérieure, le fichier de configuration nginx-app.conf est inclus dans la section serveur du fichier de configuration principal NGINX. Par exemple, le fichier de configuration php-app.conf par défaut contient les éléments suivants :

location / {
# try to serve files directly, fallback to the front controller
try_files $uri /$front_controller_file$is_args$args;
}

Pour définir un fichier de configuration personnalisé, créez le fichier nginx-app.conf dans le répertoire racine de votre projet. L'environnement d'exécution remplace le fichier par défaut par le fichier que vous fournissez.

Par défaut, le contrôleur frontal du framework utilise le fichier index.php. Vous devrez peut-être modifier cette configuration en fonction de votre projet. Par exemple, le framework Symfony utilise app.php au lieu de index.php. Vous pouvez modifier le nom du fichier dans la section runtime_config de votre fichier app.yaml :

runtime: php
env: flex

runtime_config:
  document_root: .
  front_controller_file: app.php

OPcache

Activez OPcache dans votre fichier php.ini. Consultez la documentation officielle pour savoir comment configurer OPcache.

Pour désactiver OPcache, créez ou modifiez le fichier php.ini avec la ligne suivante :

opcache.enable=0

Dépendances

L'environnement d'exécution recherche un fichier composer.json dans le répertoire source de votre application et, avant de démarrer cette dernière, utilise composer pour installer les dépendances. Pour en savoir plus sur la déclaration et la gestion des packages, consultez la documentation Utiliser des bibliothèques PHP.

Utiliser des extensions PHP

Les extensions PHP suivantes sont pré-installées et activées sur le système :

Versions PHP compatibles

Vous pouvez activer les extensions suivantes à l'aide du fichier php.ini :

v7.3 et versions précédentes

Les extensions PHP suivantes sont désactivées par défaut. Vous pouvez activer les extensions suivantes dans le fichier php.ini :

Pour activer une extension, ajoutez un fichier php.ini à la racine de votre application avec la directive extension :

; Enable the Redis extension
extension=redis.so

; Enable the OpenTelemetry extension (must be in an opentelemetry section)
[opentelemetry]
extension=opentelemetry.so

Vous pouvez également activer une extension en ajoutant require au fichier composer.json :

{
    "require": {
        "ext-redis": "*"
    }
}

Ces packages permettent l'installation des extensions PHP les plus populaires. Si votre application possède des dépendances supplémentaires au niveau du système d'exploitation, vous devez étendre l'environnement d'exécution PHP ou utiliser un environnement d'exécution personnalisé pour installer les packages appropriés.

HTTPS et proxy de transfert

App Engine met fin à la connexion HTTPS au niveau de l'équilibreur de charge et transfère la requête à l'application. Le serveur NGINX est configuré pour définir la variable d'environnement HTTPS ($_SERVER["HTTPS"]) sur on lorsque la requête est effectuée via HTTPS.

Certaines applications doivent également vérifier l'adresse IP de l'utilisateur. Cette option est disponible dans l'en-tête standard X-Forwarded-For.

Fonctions désactivées

Les fonctions suivantes sont désactivées avec la directive disable_functions dans le fichier php.ini :

  • exec
  • passthru
  • proc_open
  • proc_close
  • shell_exec
  • show_source
  • symlink
  • system

Si vous avez besoin de l'une des fonctions ci-dessus, ajoutez un fichier php.ini à la racine de votre application et modifiez la directive disable_functions. Vous pouvez également définir whitelist_functions dans la section runtime_config du fichier app.yaml sur une liste de fonctions autorisées, séparées par des virgules.

Pour PHP version 7.3 et antérieure, l'extension Security suhosin est installée et configurée par défaut pour s'exécuter en mode simulation. Le mode simulation enregistre l'utilisation de fonctions potentiellement dangereuses, qui s'afficheront dans l'interface utilisateur de Cloud Logging. Si vous désactivez le mode simulation, votre application se ferme lorsqu'une fonction potentiellement dangereuse est utilisée. Pour activer cette fonctionnalité de sécurité supplémentaire, ajoutez un fichier php.ini à la racine de votre projet avec l'option suivante :

; Prevent the use of potentially dangerous functions rather than logging them
suhosin.simulation = Off

Fonctions corrigées

La fonction parse_str est corrigée, et le deuxième paramètre est obligatoire. Si vous appelez parse_str avec un seul paramètre, un avertissement est émis et la fonction n'est pas appelée.

Configurations disponibles

Vous pouvez inclure les configurations suivantes dans la section runtime_config :

NomDescriptionValeur par défaut
document_root Spécifie DOCUMENT_ROOT pour nginx et PHP. Vous devez utiliser un chemin relatif partant du répertoire racine du projet. Champ obligatoire
composer_flags Vous pouvez remplacer certaines options de composition par cette clé. --no-dev --prefer-dist
enable_stackdriver_integration Compatible uniquement avec la version 7.3 et les versions antérieures. Lorsque la valeur est définie sur "true", l'environnement d'exécution active automatiquement l'intégration de Google Cloud Observability. Cette configuration nécessite le package google/cloud v0.33 ou une version ultérieure. faux
skip_lockdown_document_root Compatible uniquement avec la version 7.3 et les versions antérieures. Par défaut, l'environnement d'exécution définit une autorisation stricte en lecture seule sur tous les fichiers et répertoires du répertoire document_root. Lorsque la valeur est définie sur true, l'environnement d'exécution ignore la modification de l'autorisation. faux
whitelist_functions Compatible uniquement avec la version 7.3 et les versions antérieures. Liste des noms de fonctions à ajouter à la liste d'autorisation, séparés par une virgule. Une chaîne vide
front_controller_file Nom du fichier PHP par défaut pour l'accès au répertoire. index.php
nginx_conf_http_include Nom de fichier d'une configuration nginx partielle, qui sera incluse dans la section http du fichier de configuration nginx principal. nginx-http.conf
nginx_conf_include Nom de fichier d'une configuration nginx partielle, qui sera incluse dans la section server du fichier de configuration nginx principal. nginx-app.conf
nginx_conf_override Nom d'un fichier de configuration nginx fourni par l'utilisateur, qui sera utilisé comme fichier de configuration nginx principal. nginx.conf
php_fpm_conf_override Nom d'un fichier de configuration php-fpm fourni par l'utilisateur, qui sera inclus au bas de la section [app] afin de remplacer les configurations existantes. php-fpm.conf
php_ini_override Nom d'un fichier de configuration PHP fourni par l'utilisateur. php.ini
supervisord_conf_addition Nom d'un fichier de configuration supervisord fourni par l'utilisateur, qui sera inclus dans le fichier de configuration supervisord principal. additional-supervisord.conf
supervisord_conf_override Nom d'un fichier de configuration supervisord fourni par l'utilisateur, qui remplacera le fichier de configuration supervisord principal. supervisord.conf

Vous pouvez contrôler si Nginx diffuse des fichiers statiques pour les URI correspondants en définissant la variable d'environnement NGINX_SERVES_STATIC_FILES dans la section build_env_variables de votre fichier app.yaml:

runtime: php
env: flex

runtime_config:
  document_root: "web"
  operating_system: "ubuntu22"

build_env_variables:
  NGINX_SERVES_STATIC_FILES: true

Configurer Supervisor dans l'environnement d'exécution PHP

L'environnement flexible d'App Engine utilise supervisor pour gérer les processus. Par défaut, supervisord exécute nginx et php-fpm pour exécuter des applications Web PHP. Toutefois, certaines applications doivent exécuter des processus externes. Parfois, ces applications n'ont même pas besoin de nginx ni de php-fpm.

Si vous souhaitez ajouter un processus géré par supervisord, ajoutez un fichier nommé additional-supervisord.conf au répertoire racine du projet. Voici un exemple de contenu de fichier de configuration pour ce cas :

[program:quote-updater]
command = php %(ENV_APP_DIR)s/worker.php
stdout_logfile = /dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile = /dev/stderr
stderr_logfile_maxbytes=0
user = www-data
autostart = true
autorestart = true
priority = 5
stopwaitsecs = 20

Si vous souhaitez remplacer nginx et php-fpm par votre processus, ajoutez un fichier nommé supervisord.conf au répertoire racine du projet. Voici un exemple de contenu de fichier de configuration pour ce scénario :

[supervisord]
nodaemon = true
logfile = /dev/null
logfile_maxbytes = 0
pidfile = /var/run/supervisord.pid

[program:react-server]
command = php %(ENV_APP_DIR)s/index.php
stdout_logfile = /dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile = /dev/stderr
stderr_logfile_maxbytes=0
user = www-data
autostart = true
autorestart = true
priority = 5
stopwaitsecs = 20

Étendre l'environnement d'exécution

L'environnement d'exécution PHP pour l'environnement flexible App Engine peut être utilisé pour créer un environnement d'exécution personnalisé. Pour en savoir plus, consultez la documentation Personnaliser l'environnement d'exécution PHP.

Variables d'environnement

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

Variable d'environnement Description
GAE_INSTANCE Le nom de l'instance actuelle.
GAE_MEMORY_MB La quantité de mémoire disponible pour le processus d'application.
GAE_SERVICE Nom du service spécifié dans le fichier app.yaml de votre application. Si aucun nom de service n'est spécifié, il est défini sur default.
GAE_VERSION Libellé de version de l'application en cours.
GOOGLE_CLOUD_PROJECT ID du projet associé à votre application, visible dans la console Google Cloud.
PORT Port qui reçoit les requêtes HTTP.

Vous pouvez définir des variables d'environnement supplémentaires à l'aide du fichier app.yaml.

Serveur de métadonnées

Chaque instance de votre application peut utiliser le serveur de métadonnées Compute Engine pour rechercher des informations sur l'instance, y compris son nom d'hôte, son adresse IP externe, son ID d'instance, ses métadonnées personnalisées et ses informations de compte de service. App Engine ne vous permet pas de définir des métadonnées personnalisées pour chaque instance, mais vous pouvez définir des métadonnées personnalisées à l'échelle du projet et les lire à partir de vos instances App Engine et Compute Engine.

Cet exemple de fonction utilise le serveur de métadonnées afin d'obtenir l'adresse IP externe de l'instance :

function get_external_ip_using_google_cloud()
{
    $metadata = new Google\Cloud\Core\Compute\Metadata();
    $externalIp = $metadata->get(
        'instance/network-interfaces/0/access-configs/0/external-ip');

    return $externalIp;
}

function get_external_ip_using_curl()
{
    $url = 'http://metadata.google.internal/computeMetadata/v1/' .
        'instance/network-interfaces/0/access-configs/0/external-ip';

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