Il runtime di PHP

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

Versioni PHP

Utilizza PHP 8.3 buildpacks. Per l'elenco completo delle versioni PHP supportate e della relativa versione di Ubuntu, consulta la pianificazione del supporto del runtime.

Per utilizzare una versione PHP supportata, devi:

  • Installa gcloud CLI versione 420.0.0 o successiva. 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 tuo 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 directory principale del documento, ti consigliamo di utilizzare una sottodirectory per l'impostazione document_root.

    Il codice sorgente si trova nel percorso /workspace anziché la directory radice (/). Se sostituisci una configurazione, i processi NGINX o supervisor fanno riferimento al tuo file di configurazione in questa directory. A aggiornare i riferimenti corrispondenti, devi:

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

    • Alcuni file, come gzip_params, non sono inclusi. Come riferimento inclusi i tuoi o una copia di GitHub. File come mime.types e fastcgi_params sono disponibili nella directory /etc/nginx.

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

  • Facoltativamente, puoi specificare una versione del runtime:

    • Include runtime_version nel tuo app.yaml. Per impostazione predefinita, viene utilizzata la versione PHP più recente se l'impostazione runtime_version non è specificata.

      • Per specificare PHP 8.3 su Ubuntu 22:

        runtime: php
env: flex

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

      • Per specificare la versione PHP più recente supportata su Ubuntu 22:

          runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: .

    • Includi una versione PHP nel file composer.json.

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

    Per ulteriori informazioni, consulta il riferimento di app.yaml.

Versioni precedenti del runtime

Per utilizzare PHP versione 7.3 e precedenti, devi:

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

    runtime: php
env: flex
api_version: 1

runtime_config:
  document_root: .

    Anche se puoi specificare la directory principale del progetto (.) come principale del documento, ti consigliamo di utilizzare una sottodirectory per document_root dell'ambientazione.

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

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

Supporto di altri runtime PHP

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

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

Personalizzare NGINX

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

Per impostazione predefinita, il front controller del framework utilizza il file index.php. Tu potrebbe essere necessario modificarlo in qualcosa di diverso per il tuo progetto. Ad esempio, il framework Symfony utilizza app.php anziché index.php. Puoi modificare nome file nella sezione runtime_config del tuo 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, è incluso il file di configurazione nginx-app.conf nella sezione server del file di configurazione NGINX principale. Ad esempio, il file di configurazione predefinito 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 sostituisce il file predefinito con il file che fornisci.

Per impostazione predefinita, il controller front del framework utilizza il file index.php. Tu potrebbe essere necessario modificarlo in qualcosa di diverso 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

Attiva 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 su come dichiarare e gestire i pacchetti, consulta Utilizzare le librerie PHP.

Utilizzo delle estensioni PHP

Le seguenti estensioni PHP sono preinstallate e abilitate nel sistema:

Versioni PHP supportate

Puoi attivare le seguenti estensioni utilizzando il file php.ini:

7.3 e precedenti

Le seguenti estensioni PHP sono disattivate per impostazione predefinita. Puoi attivare le seguenti estensioni nel file php.ini:

Per attivare un'estensione, aggiungi un file php.ini nella radice del tuo con l'istruzione 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 un require al tuo composer.json:

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

Questi pacchetti consentono l'installazione delle estensioni PHP più diffuse. 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 inoltro

App Engine termina la connessione HTTPS al bilanciatore del carico e inoltra 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 verificare l'indirizzo IP dell'utente. Questo è disponibile nell'intestazione X-Forwarded-For standard.

Funzioni disattivate

Le seguenti funzioni vengono disattivate con la direttiva disable_functions in php.ini:

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

Se hai bisogno di una delle funzioni precedenti, aggiungi un file php.ini nella directory principale della tua applicazione e modifica la direttiva disable_functions. In alternativa, imposta whitelist_functions nella sezione runtime_config in app.yaml su un un elenco di funzioni delimitato da virgole da consentire.

Per PHP 7.3 e versioni 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'uso di funzioni potenzialmente pericolose, che verranno mostrate nell'interfaccia utente di Cloud Logging. Se disattivi la modalità di simulazione, la tua applicazione verrà chiusa quando viene utilizzata una funzione potenzialmente pericolosa. Per abilitare questa funzionalità di sicurezza aggiuntiva, aggiungi php.ini nella directory radice del progetto con la seguente opzione:

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

Funzioni corrette

La funzione parse_str è oggetto di patch 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

Nella sezione runtime_config puoi includere le seguenti configurazioni:

NomeDescrizioneValore predefinito
document_root Specifica DOCUMENT_ROOT per nginx e PHP. Devi utilizzare un percorso relativo dalla directory principale del progetto. Campo obbligatorio
composer_flags Puoi sostituire alcuni flag del compositore con questa chiave. --no-dev --prefer-dist
enable_stackdriver_integration Supportato solo per la versione 7.3 e precedenti. Se impostato su true, il runtime attiverà automaticamente l'integrazione di Google Cloud Observability. Questa configurazione richiede il pacchetto google/cloud versione 0.33 o successive. falso
skip_lockdown_document_root Supportata solo per la versione 7.3 e precedenti. Per impostazione predefinita, il runtime imposterà un'autorizzazione rigida di sola lettura su tutti i i file e le directory nella directory document_root. Se impostato su true, il runtime salta la modifica dell'autorizzazione. falso
whitelist_functions Supportata solo per la versione 7.3 e precedenti. Un elenco separato da virgole di nomi di funzioni da inserire nella lista consentita. Una stringa vuota
front_controller_file Nome file PHP predefinito per l'accesso alla directory. index.php
nginx_conf_http_include Nome file di una configurazione nginx parziale, che verrà incluso nel Sezione http nel file di configurazione nginx principale. nginx-http.conf
nginx_conf_include Nome del file di una configurazione nginx parziale che verrà inclusa nella sezione server del file di configurazione nginx principale. nginx-app.conf
nginx_conf_override Nome file di un file di configurazione nginx fornito dall'utente, che verrà utilizzato il file di configurazione principale nginx. nginx.conf
php_fpm_conf_override Nome del file di configurazione php-fpm fornito dall'utente, che verrà incluso nella parte inferiore della sezione [app] in modo da sostituire le configurazioni esistenti. php-fpm.conf
php_ini_override Nome file di un file di configurazione PHP fornito dall'utente. php.ini
supervisord_conf_addition Nome file di un file di configurazione supervisore fornito dall'utente, che verrà incluso nel file di configurazione principale di supervisord. additional-supervisord.conf
supervisord_conf_override Nome file di un file di configurazione supervisore fornito dall'utente, che sostituirà il file di configurazione principale di supervisord. supervisord.conf

Puoi controllare se Nginx serve 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 le procedure. Per impostazione predefinita, supervisord esegue nginx e php-fpm per eseguire applicazioni web PHP; tuttavia alcune applicazioni devono eseguire i processi esterni. Inoltre, a volte queste applicazioni non richiedono nginx o php-fpm.

Se vuoi aggiungere un processo gestito da supervisord, aggiungi un file denominato additional-supervisord.conf alla directory principale del progetto. La di seguito è riportato un esempio di contenuto 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 il tuo processo, aggiungi un file denominato supervisord.conf nella directory principale del progetto. Le seguenti Ecco un esempio di contenuto 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 del runtime

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

Variabili di ambiente

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

Variabile di ambiente Descrizione
GAE_INSTANCE Il nome dell'istanza corrente.
GAE_MEMORY_MB La quantità di memoria disponibile per il processo di richiesta.
GAE_SERVICE Il nome del servizio specificato nel campo app.yaml dell'applicazione o, se non viene specificato alcun nome di servizio, viene impostato su default.
GAE_VERSION L'etichetta della versione dell'applicazione corrente.
GOOGLE_CLOUD_PROJECT L'ID progetto associato alla tua applicazione, visibile in la console Google Cloud
PORT La porta che riceverà le richieste HTTP.

Puoi impostare altre variabili di ambiente con app.yaml.

Server metadati

Ogni istanza della tua applicazione può utilizzare il server metadati di Compute Engine per eseguire query sulle informazioni sull' istanza, inclusi il nome host, l'indirizzo IP esterno, l'ID istanza, i metadati personalizzati e i dati dell'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 leggili dalla tua app di Compute Engine e le istanze di Compute Engine.

Questa funzione di esempio utilizza il server dei metadati per recuperare 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);
}