Accede a servicios agrupados en paquetes heredados en PHP 7/8

En esta página, se describe cómo instalar y usar los servicios agrupados en paquetes con el entorno de ejecución de PHP 7/8 para el entorno estándar de App Engine. Tu aplicación puede acceder a los servicios agrupados en paquetes mediante el SDK de servicios de App Engine para PHP 7/8.

Antes de comenzar

Consulta la lista de APIs de servicios agrupados en paquetes heredados que puedes llamar en el entorno de ejecución de PHP 7/8.
Actualiza el archivo app.yaml para que incluya la siguiente línea:
```
app_engine_apis: true
```
Para probar tu app de PHP 7/8, debes implementarla con gcloud app deploy.

Instala el SDK de App Engine para PHP

Puedes encontrar el SDK de App Engine para PHP en GitHub en appengine-php-sdk. Debes usar la versión 2.1 o una posterior para PHP 8.1+ y la versión 2.0.1 o una versión posterior, para PHP 7.x.

Hay dos formas de incorporar el SDK a tu proyecto:

Ejecuta el comando Packagist para agregar el SDK al archivo composer.json:
```
composer require google/appengine-php-sdk
```

Crea un archivo composer.json manualmente con los siguientes detalles:

PHP 7/8

{
    "require": {
        "google/appengine-php-sdk": "^2.1" // Or any later version
    }
}

En PHP 7/8, las APIs de App Engine requieren una especificación de dependencia explícita. Consulta este documento para obtener instrucciones sobre cómo incluir autoload.php.

Importa las bibliotecas

Usa el operador use para importar la clase que necesitas de la lista de API disponibles. Por ejemplo, Google\AppEngine\Api\AppIdentity\ClassName se puede importar con la declaración:

use Google\AppEngine\Api\AppIdentity\ClassName;

Consideraciones sobre la migración

Identidad de la app

No es necesario que realices cambios en la configuración de tu aplicación cuando actualices a PHP 7/8. El comportamiento, las funciones y las instrucciones de configuración para la API de App Identity permanecen iguales. Consulta la Descripción general de la API de Identity de la API y la Guía de referencia de la API de App Identity para obtener más detalles.

Correo electrónico

La API de correo electrónico de PHP 7/8 sigue siendo casi la misma que la API de correo electrónico de PHP 5, con algunas diferencias pequeñas sobre cómo habilitar o inhabilitar los servicios de correo electrónico. En las siguientes secciones, se tratan las diferencias entre ambos entornos de ejecución.

Clase de mensaje

En PHP 7/8, la clase Message funciona igual que en PHP 5.5, excepto que se actualizaron las importaciones use. Las diferencias se muestran a continuación:

PHP 5.5

use google\appengine\api\mail\Message;

PHP 7/8

use Google\AppEngine\Api\Mail\Message;

Si no puedes cambiar las declaraciones de importación, la declaración de importación original de PHP 5.5 también funcionará para PHP 7/8.

Función de correo electrónico

En PHP 5.5, la función de correo electrónico de App Engine sobrecargó la función mail() nativa de PHP.

En PHP 7/8, la función de correo electrónico de App Engine ya no se sobrecarga de forma predeterminada, y se debe habilitar de forma explícita. Este nuevo comportamiento te permite adaptar la función de correo electrónico para que se adapte mejor a tus necesidades. Este cambio también te permite tener visibilidad sobre qué implementación se está usando actualmente para todas las llamadas a funciones de correo electrónico.

Si prefieres usar la función mail() nativa de PHP para enviar correos electrónicos con la API de correo electrónico de App Engine, puedes habilitarla en tu archivo php.ini de la siguiente manera:

extension = mailparse.so
sendmail_path = "php ./vendor/google/appengine-php-sdk/src/Runtime/SendMail.php -t -i"

Como se muestra en el ejemplo anterior, agrega la extensión mailparse para habilitar la función de correo electrónico PHP nativa y establece la configuración del entorno de ejecución sendmail_path en la implementación de la función de correo electrónico de App Engine. Después de habilitar esto, todas las llamadas a mail() funcionarán exactamente como lo hicieron en PHP 5.5.

Consulta las guías Envía correos electrónicos y Recibe correos electrónicos, y la Guía de referencia de la API de correo electrónico para obtener más detalles.

Memcache

Si quieres usar Memcache para PHP 7/8,+ debes agregar una declaración explícita de las bibliotecas de Memcache. Anteriormente, Memcache para PHP 5.5 no requería una declaración explícita. Esta declaración explícita permite la flexibilidad entre el Memcache nativo de PHP y el Memcache de App Engine.

Las clases de Memcache de PHP 7/8 tienen el mismo comportamiento que las clases de PHP de PHP 5, excepto por la declaración explícita. Consulta la Descripción general de Memcache para obtener más detalles.

PHP 5.5

Ejemplo de Memcache para PHP 5.5:

$memcache = new Memcache();
return $memcache->get($key);

Ejemplo de Memcached para PHP 5.5:

$memcache = new Memcached();
$memcache->set('who', $request->get('who'));
return $twig->render('memcache.html.twig', [
    'who' => $request->get('who'),
    'count' => $memcache->increment('count', 1, 0),
    'host' => $request->getHost(),
]);

PHP 7/8

Ejemplo de API de Memcache para PHP 7/8:

use Google\AppEngine\Api\Memcache\Memcache;

$memcache = new Memcache();
return $memcache->get($key);

Ejemplo de la API de Memcached para PHP 7/8:

use Google\AppEngine\Api\Memcache\Memcached;

$memcache = new Memcached();
$memcache->set('who', $request->get('who'));
return $twig->render('memcache.html.twig', [
    'who' => $request->get('who'),
    'count' => $memcache->increment('count', 1, 0),
    'host' => $request->getHost(),
]);

Si prefieres usar el comportamiento original de Memcache para PHP 5 en PHP 7/8 y versiones posteriores, puedes continuar llamando a Memcache de manera implícita si incluyes algunas líneas más en tu archivo composer.json. Después de importar el paquete appengine-php-sdk del compositor, agrega la siguiente ruta del archivo de habilitación al elemento files en la sección autoload:

PHP 7/8

{
  "require": {
    "google/appengine-php-sdk": "^2.1" // Or any later version
  },
  "autoload": {
    "files": [
    "./vendor/google/appengine-php-sdk/src/Api/Memcache/MemcacheOptIn.php"
    ]
  }
}

Módulos

No es necesario que realices cambios en la configuración de tu aplicación cuando actualices a PHP 7/8. El comportamiento, las funciones y las instrucciones de configuración para la API de módulos siguen siendo los mismos. Consulta la Descripción general de módulos y la Guía de referencia de la API de módulos para obtener más detalles.

Sesión

Sessions de PHP 7/8 funciona de la misma manera que Sessions de PHP 5.5. Sin embargo, las instrucciones de configuración difieren porque Sessions de PHP 5.5 usaron la clase MemcacheSessionHandler de forma predeterminada.

Para usar Sessions de PHP 7/8, debes registrar la clase MemcacheSessionHandler con session_set_save_handler() y configurar session.save_path en Memcache. También debes habilitar Memcache cuando accedas a la información de Memcache.

Por ejemplo:

PHP 7/8

ini_set('session.save_path', 'Google\AppEngine\Api\Memcache\Memcache');
session_set_save_handler(new Google\AppEngine\Ext\Session\MemcacheSessionHandler(), true);

Consulta la guía de referencia de la API de sesión para obtener más detalles.

Lista de tareas en cola

No es necesario que realices cambios en la configuración de tu aplicación cuando actualices a PHP 7/8. El comportamiento, las funciones y las instrucciones de configuración para la lista de tareas en cola permanecen iguales. Consulta la sección Sesiones de la guía Descripción general de la lista de tareas en cola y la Guía de referencia de la API de la lista de tareas en cola para obtener más detalles.

Recuperación de URL

Si deseas usar la recuperación de URL para PHP 7/8, debes agregar una declaración explícita de las bibliotecas de recuperación de URL. Antes, el servicio de recuperación de URLs para PHP 5 no requería una declaración explícita y se usaba de forma implícita.

En PHP 5, el servicio de recuperación de URLs de App Engine fue la única forma de recuperar el contenido de Internet en PHP 5.5, por lo que a la mayoría de las funciones de PHP 5.5 que accedían a Internet se les aplicó un parche para usar UrlFetch de forma automática.

En PHP 7/8, las redes nativas de PHP pueden acceder a Internet, por lo que este parche automático no se realiza. En algunos casos, puedes usar el mecanismo UrlFetch original, en particular el mecanismo que proporciona el encabezado de solicitud X-Appengine-Inbound-Appid para identificar la app de App Engine que realiza una solicitud a tu aplicación de App Engine.

A fin de habilitar la recuperación de URL para PHP 7/8, puedes usar una declaración explícita en el wrapper de transmisión o usar la clase UrlFetch directamente, descrita en las siguientes secciones.

Opción 1a Controladores de flujo

Puedes habilitar el servicio de recuperación de URL de App Engine para realizar solicitudes HTTP a los controladores de transmisión PHP de http:// y https://. Para ello, siga estos pasos:

Cancela el controlador de transmisión de PHP nativo para HTTP(S) mediante stream_wrapper_unregister().
Registra HTTP(S) en la clase UrlFetchStream mediante stream_wrapper_register().
Llama a file_get_contents() con la configuración que deseas que use el wrapper de transmisión.
- Si deseas volver al controlador de transmisión de PHP nativo desde el servicio de recuperación de URLs, usa stream_wrapper_unregister() y, luego, regístrate mediante stream_wrapper_restore().

Para comparar, consulta los ejemplos equivalentes de PHP 5 y PHP 7/8:

PHP 5.5

...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using Url Fetch service. No option to use the native php stream wrapper.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

PHP 7/8

use google\appengine\api\urlfetch\UrlFetchStream;
...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using the native php stream wrapper.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

stream_wrapper_unregister("http");
stream_wrapper_register("http", "UrlFetchStream");

// Now using the Url Fetch service.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

stream_wrapper_unregister("http");
stream_wrapper_restore("http");

// Now using the native php stream wrapper again.

Opción 1b. Encabezados de respuesta HTTP con controladores de transmisión

Las instrucciones para usar encabezados de respuesta HTTP(S) con controladores de transmisión son similares a las instrucciones para usar controladores de transmisión:

Cancela el controlador de transmisión de PHP nativo para HTTP(S) mediante stream_wrapper_unregister().
Registra HTTP(S) en la clase UrlFetchStream mediante stream_wrapper_register().
Usa fopen() en lugar de file_get_contents() con la configuración que desees.
Llama a stream_get_meta_data() y extrae la información del encabezado de respuesta mediante la indexación de los metadatos para 'wrapper_data. Los encabezados de respuesta se muestran en un formato de array similar al de $http_response_header en PHP 5.5.

PHP 5.5

...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using file_get_contents and the Url Fetch service.
$result = file_get_contents('http://example.com', false, $context);

// Print Http Response Headers
print_r($http_response_header);

PHP 7/8

use google\appengine\api\urlfetch\UrlFetchStream;
...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

stream_wrapper_unregister("http");
stream_wrapper_register("http", "UrlFetchStream");

// Now using fopen and the Url Fetch service.
$result = fopen('http://example.com', 'r', false, $context);

// Print Http Response Headers
$meta_data = stream_get_meta_data($result);
$headers = $meta_data['wrapper_data'];
print_r($headers);

stream_wrapper_unregister("http");
stream_wrapper_restore("http");

Opción 2. Clase UrlFetch

La clase UrlFetch es una clase personalizada que proporciona una forma más orientada de usar el servicio de recuperación de URL para una solicitud HTTP(S) en un alcance más pequeño. A diferencia de la opción del controlador de transmisión, la clase UrlFetch no anula todas las solicitudes HTTP(S) realizadas desde funciones compatibles con el wrapper de transmisión para usar el servicio de recuperación de URL. En comparación con la opción de controlador de transmisión, la configuración de clase UrlFetch también es más simple, ya que no requiere el uso de varias API de PHP, como las siguientes:

stream_context_create()
stream_wrapper_unregister()
stream_wrapper_register()
file_get_contents()

El siguiente ejemplo de clase UrlFetch es equivalente al ejemplo del controlador de transmisión:

PHP 7/8

use google\appengine\api\urlfetch\UrlFetch;
...
$urlfetch = new UrlFetch();
$result = $urlfetch->fetch($url, 'POST', $headers, http_build_query($data));
echo $result->getContent();

Usuarios

No es necesario que realices cambios en la configuración de tu aplicación cuando actualices a PHP 7/8. El comportamiento, las funciones y las instrucciones de configuración para la API de usuarios se mantienen iguales. Si quieres obtener más detalles, consulta la Descripción general de la API de usuarios y la Guía de referencia de la API de usuarios.

Bibliotecas que aporta la comunidad

Puedes usar la API que aporta la comunidad para datastore cuando actualices a PHP 7/8.

Otras consideraciones

Para probar la funcionalidad de servicios agrupados en paquetes heredados en tu aplicación PHP 7/8, puedes usar el servidor de desarrollo local. Cuando ejecutes el comando dev_appserver.py, configura el argumento --php_executable_path como un archivo PHP 7/8 ejecutable. Ten en cuenta que esto es diferente de PHP 5, que requiere un ejecutable php-cgi.

Si el proyecto tiene un archivo composer.json, configura --php-composer-path en la ruta del archivo composer.phar.
Para implementar la app, usa el comando gcloud app deploy.
El registro en el entorno de ejecución de PHP 7/8 sigue el estándar de registro en Cloud Logging. En el entorno de ejecución de PHP 7/8, los registros de la app ya no se agrupan con los registros de solicitud, sino que están separados en registros diferentes. Para obtener más información sobre cómo leer y escribir registros, consulta la Guía de lectura y escritura de registros.

Ejemplos

Para ver ejemplos de cómo usar los servicios agrupados en paquetes heredados con PHP, descarga las muestras de código.