As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Atualização da versão 2 do AWS SDK for PHP

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

Introdução

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

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

A versão 3 AWS SDK for PHP segue os padrões PSR -4 e PSR -7 e seguirá o SemVerpadrão daqui para frente.

Outros novos recursos incluem

Camada desacoplada HTTP

Solicitações assíncronas

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

As dependências do projeto estão atualizadas

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

As opções de região e de 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 for PHP, 'version' era totalmente opcional e'region', às vezes, opcional. Na versão 3, as duas são sempre obrigatórias. Ser explícito sobre essas duas opções permite que você bloqueie a API versão e a AWS região em que você está codificando. Quando novas API versões forem criadas ou novas AWS regiões forem disponibilizadas, você ficará isolado de possíveis alterações significativas até que esteja pronto para atualizar explicitamente sua configuração.

A instanciação do cliente usa o construtor

Na versão 3 do AWS SDK for PHP, a forma como você instancia um cliente mudou. 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 do cliente na versão 3 do AWS SDK for PHP mudaram um pouco em relação à versão 2. Consulte a página Configuração da AWS SDK for PHP Versão 3 para obter uma descrição de todas as opções suportadas.

O objeto Sdk

A versão 3 do AWS SDK for PHP apresenta o Aws\Sdk objeto como substituto Aws\Common\Aws do. 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 Aws classe na versão 2 do SDK funcionasse como um localizador de serviços (sempre retornava a mesma instância de um cliente), a Sdk classe na versão 3 retorna uma nova instância de um cliente toda vez que é usada.

O Sdk objeto também não oferece suporte ao mesmo formato de arquivo de configuração da versão 2 doSDK. 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 API resultados foram alterados

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

Por exemplo, chamar o RDS DescribeEngineDefaultParametersresultado da Amazon na versão 3 agora inclui um elemento de empacotamento “EngineDefaults”. 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 for PHP. Enums eram classes concretas dentro API do público SDK que continham constantes representando grupos de valores de parâmetros válidos. Como essas enumerações são específicas para API versões, podem mudar com o tempo, podem entrar em conflito com palavras PHP reservadas e acabam não sendo muito úteis, nós as removemos na versão 3. Isso suporta a natureza baseada em dados e independente de API versão 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 lançadas por um serviço ou operação dependem da API versão usada (elas podem mudar de versão para 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 a capturar diferentes classes de exceção, mas fornece essa função sem adicionar inchaço ao. SDK

As classes de fachada estática foram removidas

Na versão 2 do AWS SDK for PHP, havia um recurso obscuro inspirado no Laravel que permitia que você enableFacades() chamasse a Aws classe para permitir o acesso estático aos vários clientes de serviço. Esse recurso vai contra as PHP melhores práticas e paramos de documentá-lo 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 for 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 search() método que permite usar JMESPathexpressões para extrair dados mais facilmente 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.

Comparando amostras de código de ambas as versões do SDK

Os exemplos a seguir mostram algumas das maneiras pelas quais o uso da versão 3 do AWS SDK for PHP pode ser diferente da versão 2.

Exemplo: operação do Amazon S3 ListObjects

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

Da 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

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

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