Entorno de ejecución de PHP

El entorno de ejecución de PHP es la pila de software encargada de instalar el código y las dependencias de tu aplicación y, luego, ejecutarla en el entorno flexible.

Versiones de PHP

PHP 8.3 usa paquetes de compilación. Para obtener la lista completa de las versiones de PHP compatibles y su versión de Ubuntu correspondiente, consulta el programa de asistencia del entorno de ejecución.

Para usar una versión de PHP compatible, debes hacer lo siguiente:

  • Instala la versión 420.0.0 o una posterior de gcloud CLI. Puedes actualizar las herramientas de la CLI si ejecutas el comando gcloud components update. Para ver la versión instalada, puedes ejecutar el comando gcloud version.

  • Incluye la configuración runtime_config y operating_system en el archivo app.yaml para especificar un sistema operativo.

  • Declara la raíz del documento de la aplicación en el archivo app.yaml:

      runtime: php
  env: flex

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

    Aunque puedes especificar el directorio raíz del proyecto (.) como la raíz del documento, te recomendamos que uses un subdirectorio para la configuración de document_root.

    El código fuente se encuentra en el directorio /workspace, en lugar del directorio raíz (/). Si anulas cualquier configuración, los procesos NGINX o supervisor hacen referencia al archivo de configuración en este directorio. Para actualizar las referencias correspondientes, debes hacer lo siguiente:

    • Actualiza las declaraciones include en la configuración de NGINX para que estén relacionadas con /workspace en lugar de /etc/nginx.

    • Algunos archivos, como gzip_params, no están incluidos. Para hacer referencia a estos archivos, incluye tu propio o copia desde GitHub. Los archivos como mime.types y fastcgi_params están disponibles en el directorio /etc/nginx.

    • Algunos módulos NGINX, como nginx-plus-module-ndk, no están instalados. Establece el valor $docroot o agrégalo de forma manual en tu archivo de configuración NGINX.

  • De manera opcional, puedes especificar una versión del entorno de ejecución de las siguientes maneras:

    • Incluye la configuración de runtime_version en tu app.yaml. De forma predeterminada, se usa la última versión de PHP si no se especifica la configuración de runtime_version.

      • Para especificar PHP 8.3 en Ubuntu 22, haz lo siguiente:

        runtime: php
env: flex

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

      • Para especificar la última versión de PHP compatible en Ubuntu 22, sigue estos pasos:

          runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: .

    • Incluye una versión de PHP en el archivo composer.json.

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

    Consulta la referencia de app.yaml para obtener más información.

Versiones anteriores del entorno de ejecución

Para usar la versión 7.3 y anteriores de PHP, debes hacer lo siguiente:

  • Declara la raíz del documento de la aplicación. Puedes hacerlo en tu archivo app.yaml:

    runtime: php
env: flex
api_version: 1

runtime_config:
  document_root: .

    Aunque puedes especificar el directorio raíz del proyecto (.) como la raíz del documento, te recomendamos que uses un subdirectorio para la configuración de document_root.

  • Especifica una versión de PHP en el archivo composer.json para evitar que la aplicación se actualice de forma automática cuando haya una nueva versión de PHP disponible.

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

Compatibilidad con otros entornos de ejecución de PHP

Si necesitas usar una versión de PHP que no es compatible, puedes crear un entorno de ejecución personalizado y seleccionar una imagen base válida con la versión de PHP que necesites.

Para las imágenes base proporcionadas por Google o las imágenes base de Docker para PHP, consulta Compila entornos de ejecución personalizados.

Personaliza NGINX

Para definir un archivo de configuración personalizado, incluye el archivo nginx-app.conf en el directorio raíz de tu proyecto.

De forma predeterminada, el controlador frontal del framework usa el archivo index.php. Es posible que debas cambiar esto a algo distinto para tu proyecto. Por ejemplo, el framework de Symfony usa app.php en lugar de index.php. Puedes cambiar el nombre del archivo en la sección runtime_config del archivo app.yaml:

runtime: php
env: flex

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

Para la versión 7.3 y las anteriores, el archivo de configuración nginx-app.conf se incluye en la sección del servidor del archivo de configuración principal NGINX. Por ejemplo, el archivo de configuración predeterminado php-app.conf contiene lo siguiente:

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

Para definir un archivo de configuración personalizado, crea el archivo nginx-app.conf en el directorio raíz de tu proyecto. El entorno de ejecución anula el archivo predeterminado con el archivo que proporcionas.

De forma predeterminada, el controlador frontal del framework usa el archivo index.php. Es posible que debas cambiar esto a algo distinto para tu proyecto. Por ejemplo, el framework de Symfony usa app.php en lugar de index.php. Puedes cambiar el nombre del archivo en la sección runtime_config del archivo app.yaml:

runtime: php
env: flex

runtime_config:
document_root: .
front_controller_file: app.php

OPcache

Habilita OPcache en el archivo php.ini. Consulta el documento oficial para saber cómo configurar OPcache.

Para inhabilitar OPcache, crea o edita el archivo php.ini con la siguiente línea:

opcache.enable=0

Dependencias

El entorno de ejecución busca un archivo composer.json en el directorio del código fuente de la aplicación y usa composer para instalar cualquier dependencia antes de iniciar la aplicación. Si quieres obtener más información para declarar y administrar paquetes, consulta Usa las bibliotecas de PHP.

Cómo usar las extensiones de PHP

Las siguientes extensiones de PHP están preinstaladas y se habilitan en el sistema:

Versiones de PHP compatibles

Puedes habilitar las siguientes extensiones con el archivo php.ini:

v7.3 y anteriores

Las siguientes extensiones de PHP están inhabilitadas de forma predeterminada. Puedes habilitar las siguientes extensiones en el archivo php.ini:

Para habilitar una extensión, agrega un archivo php.ini en la raíz de tu aplicación con la directiva extension:

; Enable the Redis extension
extension=redis.so

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

De forma alternativa, puedes agregar require a composer.json para habilitar una extensión:

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

Estos paquetes permiten la instalación de las extensiones de PHP más populares. Si tu aplicación requiere dependencias adicionales del nivel del sistema operativo, debes extender el entorno de ejecución de PHP o bien usar un entorno de ejecución personalizado para instalar los paquetes adecuados.

Proxies HTTPS y de reenvío

App Engine finaliza la conexión HTTPS en el balanceador de cargas y reenvía la solicitud a la aplicación. El servidor NGINX se configura para establecer la variable de entorno HTTPS ($_SERVER["HTTPS"]) en on cuando la solicitud se realiza a través de HTTPS.

Algunas aplicaciones también necesitan verificar la dirección IP del usuario. Esta está disponible en el encabezado estándar X-Forwarded-For.

Funciones inhabilitadas

Las siguientes funciones se inhabilitan con la directiva disable_functions en php.ini:

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

Si necesitas alguna de las funciones anteriores, agrega un archivo php.ini en la raíz de la aplicación y cambia la directiva disable_functions. También puedes configurar whitelist_functions en la sección runtime_config de app.yaml para permitir una lista delimitada por coma de funciones.

En PHP 7.3 y versiones anteriores, la extensión de Suhosin Security se instala y configura de forma predeterminada para que se ejecute en modo de simulación. El modo de simulación registra el uso de posibles funciones peligrosas, que se mostrarán en la IU de Cloud Logging. Desactivar el modo de simulación hará que la aplicación se cierre cuando se use una posible función peligrosa. Para habilitar esta función de seguridad adicional, agrega un php.ini en la raíz del proyecto con la siguiente opción:

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

Funciones con parche

La función parse_str tiene un parche y el segundo parámetro es obligatorio. Si llamas a parse_str con un solo parámetro, aparecerá un mensaje de advertencia y no se llamará a la función.

Opciones de configuración disponibles

Puedes incluir las siguientes configuraciones en la sección runtime_config:

NombreDescripciónValor predeterminado
document_root Especifica DOCUMENT_ROOT para nginx y PHP. Debes usar una ruta de acceso relativa desde el directorio raíz del proyecto. Campo obligatorio
composer_flags Puedes anular algunas de las marcas del compositor con esta clave. --no-dev --prefer-dist
enable_stackdriver_integration Solo es compatible con la versión 7.3 y anteriores. Cuando se configura como verdadero, el entorno de ejecución habilita de forma automática la integración de Google Cloud Observability. Esta configuración requiere el paquete google/cloud v0.33 o superior. falso
skip_lockdown_document_root Solo es compatible con la versión 7.3 y anteriores. De forma predeterminada, el entorno de ejecución establecerá un permiso estricto de solo lectura en todos los archivos y directorios del directorio document_root. Cuando se establece en true, el entorno de ejecución omite el cambio de permiso. falso
whitelist_functions Solo es compatible con la versión 7.3 y anteriores. Una lista separada por comas de los nombres de funciones a las listas de entidades permitidas. Una string vacía
front_controller_file El nombre de archivo PHP predeterminado para el acceso al directorio. index.php
nginx_conf_http_include El nombre de archivo de una configuración de nginx parcial, que se incluirá en la sección http en el archivo de configuración de nginx principal. nginx-http.conf
nginx_conf_include El nombre de archivo de una configuración de nginx parcial que se incluirá en la sección server en el archivo de configuración de nginx principal. nginx-app.conf
nginx_conf_override El nombre de un archivo de configuración de nginx proporcionado por el usuario, que se usará como el archivo de configuración principal de nginx. nginx.conf
php_fpm_conf_override El nombre de un archivo de configuración de php-fpm proporcionado por el usuario, que se incluirá en la parte inferior de la sección [app] para que anule las configuraciones existentes. php-fpm.conf
php_ini_override El nombre de un archivo de configuración de PHP proporcionado por el usuario. php.ini
supervisord_conf_addition El nombre de un archivo de configuración de supervisord proporcionado por el usuario, que se incluirá en el archivo de configuración principal de supervisord. additional-supervisord.conf
supervisord_conf_override El nombre de un archivo de configuración proporcionado por el usuario, que anulará el archivo de configuración principal de supervisord. supervisord.conf

Configura supervisord en el entorno de ejecución de PHP

El entorno flexible de App Engine usa supervisord para administrar los procesos. De forma predeterminada, supervisord ejecuta nginx y php-fpm para ejecutar aplicaciones web de PHP. Sin embargo, algunas aplicaciones necesitan ejecutar procesos externos. Además, estas aplicaciones a veces no requieren nginx ni php-fpm.

Si deseas agregar un proceso administrado mediante supervisord, agrega un archivo llamado additional-supervisord.conf al directorio raíz del proyecto. A continuación, se muestra un ejemplo del contenido de un archivo de configuración para este 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

Si deseas reemplazar nginx y php-fpm por tu proceso, agrega un archivo llamado supervisord.conf al directorio raíz del proyecto. A continuación, se muestra un ejemplo del contenido de un archivo de configuración para este 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

Extiende el tiempo de ejecución

El entorno de ejecución de PHP del entorno flexible de App Engine se puede usar para crear un entorno de ejecución personalizado. Consulta Personaliza el entorno de ejecución de PHP para obtener más información.

Variables de entorno

Las siguientes variables del entorno se configuran mediante el entorno de ejecución:

Variable del entorno Descripción
GAE_INSTANCE El nombre de la instancia actual.
GAE_MEMORY_MB La cantidad de memoria disponible para el proceso de la aplicación.
GAE_SERVICE El nombre del servicio especificado en el archivo app.yaml de la aplicación; si no se especifica ningún nombre, se configura como default.
GAE_VERSION La etiqueta de versión de la aplicación actual.
GOOGLE_CLOUD_PROJECT El ID del proyecto asociado con la aplicación, que se puede ver en la consola de Google Cloud.
PORT El puerto que recibirá las solicitudes HTTP.

Puedes definir variables de entorno adicionales con app.yaml.

Servidor de metadatos

Cada instancia de la aplicación puede usar el servidor de metadatos de Compute Engine para consultar la información de la instancia, incluido su nombre del host, dirección IP externa, ID de instancia, metadatos personalizados y la información de la cuenta de servicio. App Engine no permite definir metadatos personalizados para cada instancia, pero puedes definir los metadatos personalizados de todo el proyecto y leerlos desde tus instancias de App Engine y Compute Engine.

Esta función de ejemplo usa el servidor de metadatos para obtener la dirección IP externa de una instancia:

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