Il runtime PHP

Il runtime PHP è lo stack software responsabile dell'installazione del codice e delle dipendenze dell'applicazione e della sua esecuzione nell'ambiente flessibile.

Versioni di PHP

PHP 8.4 utilizza buildpack. Per l'elenco completo delle versioni di PHP supportate e della versione di Ubuntu corrispondente, consulta il programma di supporto del runtime.

Per utilizzare una versione di PHP supportata, devi:

• Installa gcloud CLI versione 420.0.0 o successive. Puoi aggiornare gli strumenti CLI eseguendo il comando gcloud components update. Per visualizzare la versione installata, puoi eseguire il comando gcloud version.

• Includi le impostazioni runtime_config e operating_system nel file app.yaml per specificare un sistema operativo.

• Dichiara la radice del documento per la tua applicazione nel file app.yaml:

    runtime: php
    env: flex
  
    runtime_config:
        operating_system: "ubuntu22"
        document_root: "web"
  

  Sebbene tu possa specificare la directory principale del progetto (.) come document root, ti consigliamo di utilizzare una sottodirectory per l'impostazione document_root.

  Il codice sorgente si trova nella directory /workspace anziché nella directory principale (/). Se esegui l'override di una configurazione, i processi NGINX o supervisor fanno riferimento al file di configurazione in questa directory. Per aggiornare i riferimenti corrispondenti, devi:

  • Aggiorna tutte le istruzioni include nella configurazione NGINX in modo che siano relative a /workspace anziché a /etc/nginx.

  • Alcuni file, come gzip_params, non sono inclusi. Per fare riferimento a questi file, includi i tuoi o copiali da GitHub. File come mime.types e fastcgi_params sono disponibili nella directory /etc/nginx.

  • Alcuni moduli NGINX, come nginx-plus-module-ndk, non sono installati. Imposta il valore $docroot o aggiungilo manualmente nel file di configurazione NGINX.

• (Facoltativo) Puoi specificare una versione del runtime:

  • Includi l'impostazione runtime_version nel tuo app.yaml. Per impostazione predefinita, viene utilizzata l'ultima versione di PHP se l'impostazione runtime_version non è specificata.

    • Per specificare PHP 8.4 su Ubuntu 22:

      runtime: php
      env: flex
      
      runtime_config:
          operating_system: "ubuntu22"
          runtime_version: "8.4"
          document_root: .
      

    • Per specificare l'ultima versione di PHP supportata su Ubuntu 22:

        runtime: php
        env: flex
      
        runtime_config:
            operating_system: "ubuntu22"
            document_root: .
      

  • Includere una versione di PHP nel file composer.json.

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

  Per saperne di più, consulta il riferimento app.yaml.

Versioni precedenti dell'ambiente di runtime

Per utilizzare PHP versione 7.3 e precedenti, devi:

• Dichiara la radice del documento per la tua applicazione. Puoi farlo nel tuo file app.yaml:

  runtime: php
  env: flex
  api_version: 1
  
  runtime_config:
    document_root: .
  

  Sebbene tu possa specificare la directory principale del progetto (.) come document root, ti consigliamo di utilizzare una sottodirectory per l'impostazione document_root.

• Specifica una versione di PHP nel file composer.json per impedire l'upgrade automatico dell'applicazione quando diventa disponibile una nuova versione di PHP.

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

Supporto di altri runtime PHP

Se devi utilizzare una versione di PHP non supportata, puoi creare un runtime personalizzato e selezionare un'immagine di base valida con la versione di PHP che ti serve.

Per le immagini di base fornite da Google o le immagini di base Docker PHP, consulta Creazione di runtime personalizzati.

Personalizzare NGINX

Per definire un file di configurazione personalizzato, includi il file nginx-app.conf nella directory principale del progetto.

Per impostazione predefinita, il controller frontale del framework utilizza il file index.php. Potresti dover modificare questo valore per il tuo progetto. Ad esempio, il framework Symfony utilizza app.php anziché index.php. Puoi modificare il nome del file nella sezione runtime_config del file app.yaml:

runtime: php
env: flex

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

Per la versione 7.3 e precedenti, il file di configurazione nginx-app.conf è incluso nella sezione server del file di configurazione principale NGINX. Ad esempio, il file di configurazione predefinita php-app.conf contiene quanto segue:

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

Per definire un file di configurazione personalizzato, crea il file nginx-app.conf nella directory principale del progetto. Il runtime esegue l'override del file predefinito con il file che fornisci.

Per impostazione predefinita, il controller frontale del framework utilizza il file index.php. Potresti dover modificare questo valore per il tuo progetto. Ad esempio, il framework Symfony utilizza app.php anziché index.php. Puoi modificare il nome del file nella sezione runtime_config del file app.yaml:

runtime: php
env: flex

runtime_config:
  document_root: .
  front_controller_file: app.php

OPcache

Abilita OPcache nel file php.ini. Consulta la documentazione ufficiale per scoprire come configurare OPcache.

Per disattivare OPcache, crea o modifica il file php.ini con la seguente riga:

opcache.enable=0

Dipendenze

Il runtime cerca un file composer.json nella directory di origine dell'applicazione e utilizza composer per installare eventuali dipendenze prima di avviare l'applicazione. Per ulteriori informazioni sulla dichiarazione e sulla gestione dei pacchetti, consulta Utilizzo delle librerie PHP.

Utilizzo delle estensioni PHP

Le seguenti estensioni PHP sono preinstallate e abilitate sul sistema:

Per attivare un'estensione, aggiungi un file php.ini nella radice della tua applicazione con la direttiva extension:

; Enable the Redis extension
extension=redis.so

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

In alternativa, puoi anche attivare un'estensione aggiungendo require al tuo composer.json:

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

Questi pacchetti consentono l'installazione delle estensioni PHP più popolari. Se la tua applicazione richiede dipendenze aggiuntive a livello di sistema operativo, devi estendere il runtime PHP o utilizzare un runtime personalizzato per installare i pacchetti appropriati.

Proxy HTTPS e di forwarding

App Engine termina la connessione HTTPS al bilanciatore del carico e inoltra la richiesta alla tua applicazione. Il server NGINX è configurato per impostare la variabile di ambiente HTTPS ($_SERVER["HTTPS"]) su on quando la richiesta viene effettuata tramite HTTPS.

Alcune applicazioni devono anche determinare l'indirizzo IP dell'utente. Questa opzione è disponibile nell'intestazione standard X-Forwarded-For.

Funzioni disattivate

Le seguenti funzioni sono disabilitate con l'istruzione disable_functions in php.ini:

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

Se hai bisogno di una delle funzioni sopra indicate, aggiungi un file php.ini nella radice della tua applicazione e modifica la direttiva disable_functions. In alternativa, imposta whitelist_functions nella sezione runtime_config di app.yaml su un elenco di funzioni consentite separate da virgole.

Per PHP versione 7.3 e precedenti, l'estensione di sicurezza suhosin è installata e configurata per impostazione predefinita per l'esecuzione in modalità di simulazione. La modalità di simulazione registra l'utilizzo di funzioni potenzialmente pericolose, che verranno visualizzate nell'interfaccia utente di Cloud Logging. Se disattivi la modalità di simulazione, l'applicazione si chiuderà quando viene utilizzata una funzione potenzialmente pericolosa. Per attivare questa funzionalità di sicurezza aggiuntiva, aggiungi un php.ini nella radice del progetto con la seguente opzione:

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

Funzioni patchate

La funzione parse_str è patchata e il secondo parametro è obbligatorio. Se chiami parse_str con un solo parametro, verrà visualizzato un avviso e la funzione non verrà chiamata.

Configurazioni disponibili

Puoi includere le seguenti configurazioni nella sezione runtime_config:

Puoi controllare se Nginx fornisce file statici per gli URI corrispondenti impostando la variabile di ambiente NGINX_SERVES_STATIC_FILES nella sezione build_env_variables del file app.yaml:

runtime: php
env: flex

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

build_env_variables:
  NGINX_SERVES_STATIC_FILES: true

Configurazione di supervisord nel runtime PHP

L'ambiente flessibile di App Engine utilizza supervisord per gestire i processi. Per impostazione predefinita, supervisord esegue nginx e php-fpm per eseguire applicazioni web PHP; tuttavia, alcune applicazioni devono eseguire processi esterni. Inoltre, a volte queste applicazioni non hanno nemmeno bisogno di nginx né di php-fpm.

Se vuoi aggiungere un processo gestito da supervisord, aggiungi un file denominato additional-supervisord.conf alla directory root del progetto. Di seguito è riportato un esempio di contenuti del file di configurazione per questo caso:

[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

Se vuoi sostituire nginx e php-fpm con la tua procedura, aggiungi un file denominato supervisord.conf alla directory principale del progetto. Di seguito è riportato un esempio di contenuti del file di configurazione per questo caso:

[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

Estensione della durata

Il runtime PHP dell'ambiente flessibile di App Engine può essere utilizzato per creare un runtime personalizzato. Per ulteriori informazioni, consulta Personalizzazione del runtime PHP.

Variabili di ambiente

Le seguenti variabili di ambiente sono impostate dall'ambiente di runtime:

Puoi impostare variabili di ambiente aggiuntive con app.yaml.

Server di metadati

Ogni istanza della tua applicazione può utilizzare il server metadati di Compute Engine per eseguire query sulle informazioni relative all'istanza, tra cui il nome host, l'indirizzo IP esterno, l'ID istanza, i metadati personalizzati e le informazioni sull'account di servizio. App Engine non ti consente di impostare metadati personalizzati per ogni istanza, ma puoi impostare metadati personalizzati a livello di progetto e leggerli dalle istanze App Engine e Compute Engine.

Questa funzione di esempio utilizza il server dei metadati per ottenere l'indirizzo IP esterno di un'istanza:

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