Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Actualización desde la versión 2 del AWS SDK for PHP

En este tema se muestra cómo migrar el código para usar la versión 3 de AWS SDK for PHP y en qué se diferencia la nueva versión de la versión 2 deSDK.

Introducción

La versión 3 de la AWS SDK for PHP representa un esfuerzo significativo para mejorar las capacidades de laSDK, incorporar más de dos años de comentarios de los clientes, actualizar nuestras dependencias, mejorar el rendimiento y adoptar los PHP estándares más recientes.

¿Qué novedades incluye la versión 3?

La versión 3 AWS SDK for PHP sigue los estándares PSR -4 y PSR -7 y seguirá el SemVerestándar en el futuro.

Otras nuevas características

Capa desacoplada HTTP

Solicitudes asíncronas

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

Las dependencias del proyecto están actualizadas

Las dependencias del SDK han cambiado en esta versión.

Ahora se requieren las opciones Region y Version

Al crear una instancia de un cliente para cualquier servicio, especifique las opciones 'region' y 'version'. En la versión 2 de AWS SDK for PHP, 'version' era completamente opcional y, a veces, 'region' era opcional. En la versión 3, ambas son siempre necesarias. Ser explícito en cuanto a estas dos opciones te permite fijar la API versión y la AWS región en las que estás codificando. Cuando se creen nuevas API versiones o haya nuevas AWS regiones disponibles, estarás protegido de posibles cambios importantes hasta que estés preparado para actualizar tu configuración de forma explícita.

La creación de instancias del cliente utiliza el constructor

En la versión 3 de AWS SDK for PHP, la forma de crear instancias 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 de la versión 3 AWS SDK for PHP han cambiado un poco con respecto a la versión 2. Consulte la página de configuración de la AWS SDK for PHP versión 3 para obtener una descripción de todas las opciones compatibles.

El objeto Sdk

La versión 3 de AWS SDK for PHP presenta el Aws\Sdk objeto como reemplazo de. 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 Aws clase de la versión 2 de la SDK funcionaba como un localizador de servicios (siempre devolvía la misma instancia de un cliente), la Sdk clase de la versión 3 devuelve una nueva instancia de un cliente cada vez que se usa.

El Sdk objeto tampoco admite el mismo formato de archivo de configuración que en la versión 2 deSDK. 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 API resultados han cambiado

Para proporcionar coherencia en la forma en que SDK analiza el resultado de una API operación, Amazon ElastiCacheRDS, Amazon y Amazon Redshift ahora incluyen un elemento de envoltura adicional en API algunas respuestas.

Por ejemplo, llamar al RDS DescribeEngineDefaultParametersresultado de Amazon en la versión 3 ahora incluye un elemento envolvente «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 for PHP. Las enumeraciones eran clases concretas entre el público API del mundo SDK que contenían constantes que representaban grupos de valores de parámetros válidos. Como estas enumeraciones son específicas de cada API versión, pueden cambiar con el tiempo, pueden entrar en conflicto con palabras PHP reservadas y, por lo tanto, no son muy útiles, las eliminamos en la versión 3. Esto confirma la naturaleza independiente de la API versión 3, basada en datos e independiente de las versiones.

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 generadas por un servicio u operación dependen de la API versión que se utilice (pueden cambiar de una versión a otra). 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. Esto equivale funcionalmente a detectar diferentes clases de excepciones, pero proporciona esa función sin añadir hinchazón a la. SDK

Se han eliminado las clases Facade estáticas

En la versión 2 de AWS SDK for PHP, había una característica poco conocida inspirada en Laravel que permitía utilizar la Aws clase para permitir enableFacades() el acceso estático a los distintos clientes del servicio. Esta función va en contra de las PHP mejores prácticas y 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 AWS SDK for PHP tenía una función denominada * 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 Paginator tienen un search() método que permite utilizar JMESPathexpresiones para extraer datos del conjunto de resultados con mayor facilidad.

$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

Los siguientes ejemplos muestran algunos de los aspectos en los que el uso de la versión 3 AWS SDK for PHP puede diferir del de la versión 2.

Ejemplo: ListObjects operación de Amazon S3

A partir de 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";
}

A partir de 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

A partir de 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.

A partir de 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.