Migração da versão 2 do AWS SDK para PHP

Este tópico mostra como migrar o código para usar a versão 3 do AWS SDK para PHP e como a nova versão difere da versão 2 do SDK.

Introdução

A versão 3 do AWS SDK para PHP representa um esforço significativo para melhorar os recursos do SDK, incorporar mais de dois anos de comentários dos clientes, atualizar nossas dependências, melhorar o desempenho e adotar os padrões de PHP mais recentes.

O que há de novo na versão 3?

A versão 3 do AWS SDK para PHP segue os padrões PSR-4 e PSR-7 e seguirá o padrão SemVer no futuro.

Outros atributos novos incluem:

Camada HTTP separada

Solicitações assíncronas

O que há de diferente da versão 2?

As dependências do projeto foram atualizadas

As dependências do SDK foram alteradas nesta versão.

As opções de região e versão agora são obrigatórias

Ao instanciar um cliente para qualquer serviço, especifique as opções 'region' e 'version'. Na versão 2 do AWS SDK para PHP, a 'version' era totalmente opcional, e a 'region' era opcional às vezes. Na versão 3, as duas são sempre obrigatórias. Ser explícito quanto a essas duas opções permite bloquear a versão da API e a região da AWS na qual você está codificando. Quando outras versões da API forem criadas ou novas regiões da AWS se tornarem disponíveis, você estará isolado de alterações que possam causam interrupções até estar tudo pronto para atualizar explicitamente sua configuração.

A instanciação do cliente usa o construtor

Na versão 3 do AWS SDK para PHP, a maneira como você instancia um cliente foi alterada. Em vez dos métodos de factory na versão 2, você pode simplesmente instanciar um cliente usando a palavra-chave 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'
]);

A configuração do cliente foi alterada

As opções de configuração de clientes na versão 3 do AWS SDK para PHP foram alteradas um pouco em relação à versão 2. Consulte a página Configuração do AWS SDK para PHP Versão 3 para obter uma descrição de todas as opções compatíveis.

O objeto Sdk

A versão 3 do AWS SDK para PHP apresenta o objeto Aws\Sdk como uma substituição do Aws\Common\Aws. O objeto Sdk atua como uma fábrica de cliente e é usado para gerenciar as opções de configuração compartilhadas entre vários clientes.

Embora a classe Aws na versão 2 do SDK funcionasse como um localizador de serviço (ela sempre retornava a mesma instância de um cliente), a classe Sdk na versão 3 retorna uma nova instância de um cliente sempre que é usada.

O objeto Sdk também não é compatível com o mesmo formato de arquivo de configuração da versão 2 do SDK. Esse formato de configuração era específico ao Guzzle 3 e agora está obsoleto. A configuração pode ser feita de forma mais simples com matrizes básicas e está documentada em Uso da classe Sdk.

Alguns resultados da API foram alterados

Para fornecer consistência na forma como o SDK analisa o resultado de uma operação da API, o Amazon ElastiCache, o Amazon RDS e o Amazon Redshift agora têm um elemento de encapsulamento adicional em algumas respostas da API.

Por exemplo, chamar o resultado DescribeEngineDefaultParameters do Amazon RDS na versão 3 agora inclui um elemento “EngineDefaults” de encapsulamento. Na versão 2, esse elemento não estava presente.

$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'];

As operações a seguir são afetadas e agora contêm um elemento de encapsulamento na saída do resultado (fornecido abaixo entre parênteses):

As classes de Enum foram removidas

Removemos as classes de Enum (por exemplo, Aws\S3\Enum\CannedAcl) que existiam na versão 2 do AWS SDK para PHP. As Enums eram classes concretas dentro da API pública do SDK que continham constantes que representavam grupos de valores de parâmetros válidos. Como essas enums são específicas às versões da API, podem mudar ao longo do tempo, podem entrar em conflito com palavras reservadas do PHP e acabaram não sendo muito úteis, elas foram removidas da versão 3. Isso oferece suporte ao controle por dados e à natureza agnóstica à versão da API da versão 3.

Em vez de usar valores de objetos Enum, use os valores literais diretamente (por exemplo, CannedAcl::PUBLIC_READ → 'public-read').

As classes de exceção refinada foram removidas

Removemos as classes de exceção refinada que existiam nos namespaces de cada serviço (por exemplo, Aws\Rds\Exception\{SpecificError}Exception) por motivos muito semelhantes aos da remoção das Enums. As exceções geradas por um serviço ou operação dependem de qual versão da API é usada (elas podem mudar de versão para a versão). Além disso, a lista completa das exceções que podem ser geradas por uma operação não está disponível, o que tornou as classes de exceção refinada da versão 2 incompletas.

Lide com erros capturando a classe da exceção raiz de cada serviço (por exemplo, ).., Aws\Rds\Exception\RdsException). Você pode usar o método getAwsErrorCode() da exceção para verificar se há códigos de erro específicos. Isso é funcionalmente equivalente à captura de classes de diferentes exceções, mas fornece essa função sem sobrecarregar o SDK.

As classes de fachada estática foram removidas

Na versão 2 do AWS SDK para PHP, havia um recurso obscuro inspirado pelo Laravel que permitia chamar enableFacades() na classe Aws para habilitar o acesso estático a vários clientes de serviços. Esse recurso viola as melhores práticas do PHP e interrompemos sua documentação há mais de um ano. Na versão 3, esse recurso foi completamente removido. Recupere seus objetos de cliente do objeto Aws\Sdk e use-os como instâncias do objetos, não como classes estáticas.

Os paginadores substituem o iteradores

A versão 2 do AWS SDK para PHP tinha um recurso chamado * iterators*. Esses recursos eram objetos que eram usados para iterar sobre resultados paginados. Uma reclamação que tivemos sobre eles foi que não eram suficientemente flexíveis, porque o iterador só emitia valores específicos de cada resultado. Se houvesse outros valores necessários nos resultados, só era possível recuperá-los por meio de ouvintes de eventos.

Na versão 3, os iteradores foram substituídos por Paginadores. O objetivo é semelhante, mas os paginadores são mais flexíveis. Isso ocorre porque eles geram objetos de resultados em vez de valores de uma resposta.

Os exemplos a seguir mostram como os paginadores são diferentes dos iteradores, demonstrando como recuperar os resultados paginados para a operação S3 ListObjects na versão 2 e na versão 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";
    }
}

Os objetos do paginador têm um método search() que permite que você use expressões do JMESPath mais facilmente para extrair dados do conjunto de resultados.

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

Muitas abstrações de nível superior foram alteradas

Em geral, muitas das abstrações de nível superior (objetos auxiliares específicos ao serviço, além dos clientes) foram aprimorados ou atualizados. Alguns foram até removidos.

Comparação dos códigos de exemplo das duas versões do SDK

Os exemplos a seguir mostram algumas das maneiras pelas quais o uso da versão 3 do AWS SDK para PHP difere da versão 2.

Exemplo: operação ListObjects do Amazon S3

Na versão 2 do 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";
}

Na versão 3 do SDK

Principais diferenças:

<?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";
}

Exemplo: instanciação de um cliente com configuração global

Na versão 2 do 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.

Na versão 3 do SDK

Principais diferenças:

<?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.