Migración desde la versión 2 del AWS SDK para PHP

En este tema se muestra cómo migrar su código para utilizar la versión 3 de AWS SDK para PHP y las diferencias de la nueva versión frente a la versión 2 del SDK.

Introducción

La versión 3 de AWS SDK para PHP representa una mejora importante de las capacidades del SDK, incorpora los comentarios realizados por nuestros clientes a lo largo de dos años, la actualización de nuestras dependencias, la mejora del rendimiento y la adopción de los estándares más recientes de PHP.

¿Qué novedades incluye la versión 3?

A partir de este momento, la versión 3 de AWS SDK para PHP sigue los estándares PSR-4 y PSR-7 y el estándar SemVer.

Otras nuevas características incluyen:

Capa HTTP desacoplada

Solicitudes asíncronas

¿Cuáles son las diferencias con la versión 2?

Se han actualizado las dependencias del proyecto

En esta versión, las dependencias del SDK han cambiado.

Ahora se requieren las opciones de región y versión

Al crear una instancia de un cliente para cualquier servicio, especifique las opciones 'region' y 'version'. En la versión 2 de AWS SDK para PHP, 'version' era totalmente opcional y 'region', a veces. En la versión 3, ambas son siempre necesarias. Al ser explícito sobre ambas opciones, le permite bloquear la versión de la API y la región de AWS sobre las que está codificando. Cuando se creen versiones de la API nuevas o haya nuevas regiones de AWS disponibles, estará aislado de posibles cambios bruscos hasta que esté listo para actualizar su configuración de forma explícita.

En la creación de instancias del cliente se utiliza el constructor

En la versión 3 de AWS SDK para PHP, la forma en la que crea la instancia de un cliente ha cambiado. En lugar de utilizar los métodos factory de la versión 2, aquí puede crear una instancia de un cliente utilizando la palabra clave new.

use Aws\DynamoDb\DynamoDbClient;

// Version 2 style
$client = DynamoDbClient::factory([
    'region'  => 'us-east-2'
]);

// Version 3 style
$client = new DynamoDbClient([
    'region'  => 'us-east-2',
    'version' => '2012-08-10'
]);

La configuración del cliente ha cambiado

Las opciones de configuración del cliente en la versión 3 de AWS SDK para PHP han cambiado un poco respecto a la versión 2. Consulte la página Configuración de la versión 3 de AWS SDK para PHP para ver una descripción de todas las opciones admitidas.

El objeto Sdk

La versión 3 de AWS SDK para PHP presenta el objeto Aws\Sdk en sustitución del Aws\Common\Aws. El objeto Sdk actúa como una fábrica de cliente y se utiliza para administrar las opciones de configuración compartidas en varios clientes.

Aunque la clase Aws de la versión 2 del SDK funcionaba como un localizador de servicio (siempre devolvía la misma instancia de un cliente), la clase Sdk de la versión 3 devuelve una nueva instancia de un cliente cada vez que se utiliza.

El objeto Sdk tampoco admite el mismo formato de archivo de configuración de la versión 2 del SDK. Dicho formato de configuración era específico de Guzzle 3 y ya está obsoleto. La configuración se puede simplificar con matrices y se documenta en Uso de la clase Sdk.

Algunos resultados de la API han cambiado

Para ser coherentes en la forma en que el SDK analiza el resultado de una operación de la API, Amazon ElastiCache, Amazon RDS y Amazon Redshift ahora tienen un elemento de encapsulamiento adicional en algunas respuestas de la API.

Por ejemplo, al llamar al resultado de DescribeEngineDefaultParameters de Amazon RDS en la versión 3 ahora se incluye un elemento de encapsulamiento “EngineDefaults”. En la versión 2, este elemento no existía.

$client = new Aws\Rds\RdsClient([
    'region'  => 'us-west-1',
    'version' => '2014-09-01'
]);

// Version 2
$result = $client->describeEngineDefaultParameters();
$family = $result['DBParameterGroupFamily'];
$marker = $result['Marker'];

// Version 3
$result = $client->describeEngineDefaultParameters();
$family = $result['EngineDefaults']['DBParameterGroupFamily'];
$marker = $result['EngineDefaults']['Marker'];

Estas son las operaciones afectadas y ahora contienen un elemento de encapsulamiento en la salida del resultado (incluido a continuación entre paréntesis):

Se han eliminado las clases Enum

Hemos eliminado las clases Enum (por ejemplo, Aws\S3\Enum\CannedAcl) de la versión 2 de AWS SDK para PHP. Las clases Enum eran clases concretas dentro de la API pública del SDK que incluían constantes que representan grupos de valores de parámetros válidos. Dado que estos objetos Enum son específicos de las versiones de la API, pueden cambiar con el paso del tiempo, pueden entrar en conflicto con palabras reservadas de PHP y acabar no siendo muy útiles, los hemos eliminado de la versión 3. Esto es compatible con la naturaleza agnóstica de la versión de la API y basada en datos de la versión 3.

En lugar de utilizar valores de objetos Enum, utilice los valores literales directamente (por ejemplo, CannedAcl::PUBLIC_READ → 'public-read').

Se han eliminado las clases de excepción detalladas

Hemos eliminado las clases de excepción detalladas que existían en los espacios de nombres de cada servicio (por ejemplo, Aws\Rds\Exception\{SpecificError}Exception) por motivos muy similares por los que hemos eliminado los objetos Enum. Las excepciones que lanza un servicio u operación dependen de la versión de la API que se utiliza (pueden cambiar de versión a versión). Además, la lista completa de excepciones que puede lanzar una operación determinada no está disponible, lo que provocaba que las clases de excepción detalladas de la versión 2 fueran incompletas.

Gestione los errores capturando la clase de excepción raíz de cada servicio (por ejemplo, ).., Aws\Rds\Exception\RdsException). Puede utilizar el método getAwsErrorCode() de la excepción para comprobar si hay códigos de error específicos. Desde el punto de vista funcional, es similar a la captura de diferentes clases de excepción pero proporciona dicha función sin añadir sobredimensionamiento al SDK.

Se han eliminado las clases Facade estáticas

En la versión 2 de AWS SDK para PHP, había una característica oculta inspirada por Laravel que permitía llamar a enableFacades() en la clase Aws para habilitar el acceso estático a los distintos clientes de servicios. Esta característica es contraria a las prácticas recomendadas de PHP, por lo que dejamos de documentarla hace más de un año. En la versión 3, esta característica se ha eliminado por completo. Recupere sus objetos de cliente del objeto Aws\Sdk y utilícelos como instancias de objeto, no como clases estáticas.

Los paginadores sustituyen a los iteradores

La versión 2 de AWS SDK para PHP tenía una característica llamada *iteradores*. Estos objetos se utilizaban para la iteración de los resultados paginados. Una de las quejas que recibimos al respecto era que no eran suficientemente flexibles, ya que el iterador solo emitía valores específicos de cada resultado. Si necesitaba otros valores de los resultados, solo se podían recuperar a través de los agentes de escucha.

En la versión 3, los iteradores se han sustituido por Paginadores. Su finalidad es similar, pero los paginadores son más flexibles. Esto se debe a que generaban objetos Result en lugar de valores de una respuesta.

En los siguientes ejemplos se muestra la diferencia entre los paginadores y los iteradores, y se explica cómo recuperar resultados paginados para la operación S3 ListObjects tanto en la versión 2 como en la versión 3.

// Version 2
$objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($objects as $object) {
    echo $object['Key'] . "\n";
}

// Version 3
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($results as $result) {
    // You can extract any data that you want from the result.
    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
}

Los objetos del paginador tienen un método search() que le permite utilizar expresiones JMESPath para extraer datos más fácilmente del conjunto de resultados.

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($results->search('Contents[].Key') as $key) {
    echo $key . "\n";
}

Han cambiado muchas abstracciones de nivel superior

En general, muchas de las abstracciones de nivel superior (objetos auxiliares específicos de servicios, aparte de los clientes) se han mejorado o actualizado. Y algunas se han eliminado.

Comparación de ejemplos de código de ambas versiones del SDK

En los siguientes ejemplos se muestran algunas de las diferencias entre utilizar la versión 3 del AWS SDK para PHP y utilizar la versión 2.

Ejemplo: operación ListObjects de Amazon S3

En la versión 2 del SDK

<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = S3Client::factory([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

En la versión 3 del SDK

Diferencias clave:

<?php

require '/path/to/vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\S3\Exception\S3Exception;

$s3 = new S3Client([
    'profile' => 'my-credential-profile',
    'region'  => 'us-east-1',
    'version' => '2006-03-01'
]);

try {
    $result = $s3->listObjects([
        'Bucket' => 'amzn-s3-demo-bucket',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

Ejemplo: crear una instancia de un cliente con configuración global

En la versión 2 del SDK

<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'default_settings' => array(
            'params' => array(
                'profile' => 'my_profile',
                'region'  => 'us-east-1'
            )
        ),
        'dynamodb' => array(
            'extends' => 'dynamodb',
            'params' => array(
                'region'  => 'us-west-2'
            )
        ),
    )
);

<?php

require '/path/to/vendor/autoload.php';

use Aws\Common\Aws;

$aws = Aws::factory('path/to/my/config.php');

$sqs = $aws->get('sqs');
// Note: SQS client will be configured for us-east-1.

$dynamodb = $aws->get('dynamodb');
// Note: DynamoDB client will be configured for us-west-2.

En la versión 3 del SDK

Diferencias clave:

<?php

require '/path/to/vendor/autoload.php';

$sdk = new Aws\Sdk([
    'profile' => 'my_profile',
    'region' => 'us-east-1',
    'version' => 'latest',
    'DynamoDb' => [
        'region' => 'us-west-2',
    ],
]);

$sqs = $sdk->createSqs();
// Note: Amazon SQS client will be configured for us-east-1.

$dynamodb = $sdk->createDynamoDb();
// Note: DynamoDB client will be configured for us-west-2.