Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Mise à niveau depuis la version 2 du AWS SDK for PHP

Cette rubrique explique comment migrer votre code pour utiliser la version 3 du AWS SDK for PHP et en quoi la nouvelle version diffère de la version 2 duSDK.

Introduction

La version 3 AWS SDK for PHP représente un effort important pour améliorer les capacités duSDK, intégrer plus de deux ans de commentaires des clients, mettre à niveau nos dépendances, améliorer les performances et adopter les dernières PHP normes.

Nouveautés de la version 3

La version 3 AWS SDK for PHP suit les normes PSR -4 et PSR -7 et suivra la SemVernorme à l'avenir.

Les autres nouvelles fonctions sont les suivantes :

Couche découplée HTTP

Requêtes asynchrones

Changements par rapport à la version 2

Dépendances du projet mises à jour

Les dépendances du SDK ont changé dans cette version.

Les options Région et Version sont maintenant obligatoires

Lors de l'instanciation d'un client pour n'importe quel service, spécifiez les options 'region' et 'version'. Dans la version 2 du AWS SDK for PHP, 'version' était totalement optionnel, et 'region' était parfois facultatif. Dans la version 3, les deux sont toujours requis. Le fait d'être explicite au sujet de ces deux options vous permet de vous connecter à la API version et à AWS la région dans lesquelles vous codez. Lorsque de nouvelles API versions sont créées ou que de nouvelles AWS régions sont disponibles, vous êtes isolé des modifications potentiellement importantes jusqu'à ce que vous soyez prêt à mettre à jour explicitement votre configuration.

L'instantiation client utilise le Constructeur

Dans la version 3 de AWS SDK for PHP, la façon dont vous instanciez un client a changé. A la place des méthodes factory de la version 2, vous pouvez simplement instancier un client à l'aide du mot clé 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'
]);

Modification de la configuration du client

Les options de configuration du client dans la version 3 du AWS SDK for PHP ont légèrement changé par rapport à la version 2. Consultez la page Configuration pour la AWS SDK for PHP version 3 pour une description de toutes les options prises en charge.

L'objet Sdk

La version 3 de AWS SDK for PHP introduit l'Aws\Sdkobjet en remplacement deAws\Common\Aws. L'objet Sdk fonctionne comme une fabrique de clients. Il permet de gérer des options de configuration partagées sur plusieurs clients.

Bien que la Aws classe de la version 2 SDK fonctionnait comme un localisateur de services (elle renvoyait toujours la même instance de client), la Sdk classe de la version 3 renvoie une nouvelle instance d'un client à chaque fois qu'elle est utilisée.

L'Sdkobjet ne prend pas non plus en charge le même format de fichier de configuration que dans la version 2 duSDK. Ce format de configuration a été spécifique à Guzzle 3 et est désormais obsolète. La configuration peut être effectuée plus simplement avec des tableaux de base. Elle est documentée dans la section Utilisation de la Classe Sdk.

Certains API résultats ont changé

Pour garantir la cohérence de l'SDKanalyse du résultat d'une API opération, Amazon ElastiCache, Amazon et Amazon RDS Redshift disposent désormais d'un élément d'encapsulage supplémentaire sur API certaines réponses.

Par exemple, l'appel du RDS DescribeEngineDefaultParametersrésultat Amazon dans la version 3 inclut désormais un élément d'emballage « EngineDefaults ». Dans la version 2, cet élément n'était pas présent.

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

Les opérations suivantes sont impactées et contiennent désormais un élément d'encapsulage dans la sortie du résultat (fournis ci-dessous entre parenthèses) :

Suppression des classes Enum

Nous avons supprimé les classes Enum (par exemple, Aws\S3\Enum\CannedAcl) qui existaient dans la version 2 du kit AWS SDK for PHP. Les énumérations étaient des classes concrètes destinées au public SDK qui contenaient API des constantes représentant des groupes de valeurs de paramètres valides. Comme ces énumérations sont spécifiques aux API versions, qu'elles peuvent changer au fil du temps, qu'elles peuvent entrer en conflit avec des mots PHP réservés et qu'elles finissent par ne pas être très utiles, nous les avons supprimées dans la version 3. Cela confirme le caractère indépendant des API versions et piloté par les données de la version 3.

Au lieu d'utiliser des valeurs provenant d'objets Enum, utilisez directement les valeurs littérales (par exemple, CannedAcl::PUBLIC_READ → 'public-read').

Les classes Exception affinée ont été supprimées

Nous avons supprimé les classes Exception affinée qui existaient dans les espaces de noms de chaque service (par exemple, Aws\Rds\Exception\{SpecificError}Exception) pour des raisons similaires à celles pour lesquelles nous avons supprimé Enums. Les exceptions émises par un service ou une opération dépendent de la API version utilisée (elles peuvent changer d'une version à l'autre). De plus, la liste complète des exceptions qui peuvent être émises par une opération donnée n'est pas disponible, ce qui rend les classes d'Exception affinées de la version 2 incomplètes.

Gérez les erreurs en interceptant la classe d'exception racine pour chaque service (par exemple, Aws\Rds\Exception\RdsException). Vous pouvez utiliser la méthode getAwsErrorCode() de l'exception pour rechercher des codes d'erreur spécifiques. Cela équivaut fonctionnellement à la capture de différentes classes d'exceptions, mais fournit cette fonction sans ajouter de surcharge au. SDK

Les Classes de Façade statique ont été supprimées

Dans la version 2 du AWS SDK for PHP, il y avait une fonctionnalité obscure inspirée de Laravel qui vous permettait d'appeler enableFacades() la Aws classe pour activer un accès statique aux différents clients du service. Cette fonctionnalité va à l'encontre des PHP meilleures pratiques, et nous avons cessé de la documenter il y a plus d'un an. Dans la version 3, cette fonction est complètement supprimée. Récupérez vos objets de client à partir de l'objet Aws\Sdk et utilisez-les en tant qu'instances de l'objet, et non en tant que classes statiques.

Les programmes de pagination prévalent sur les itérateurs

La version 2 de AWS SDK for PHP avait une fonctionnalité nommée * iterators*. Il s'agissait d'objets qui étaient utilisés pour itérer sur des résultats paginés. On nous faisait souvent remarquer qu'ils n'étaient pas suffisamment flexibles, car l'itérateur émettait uniquement des valeurs spécifiques à partir de chaque résultat. Si vous aviez besoin d'autres valeurs à partir des résultats, il était possible de les récupérer uniquement via des écouteurs d'événements.

Dans la version 3, les itérateurs ont été remplacés par des programmes de pagination. Leurs objectifs sont similaires, mais les programmes de pagination sont plus flexibles. En effet, ils génèrent des objets de résultats au lieu de valeurs d'une réponse.

Les exemples suivants illustrent la façon dont les programmes de pagination sont différents des itérateurs, en démontrant comment récupérer des résultats paginés pour l'opération S3 ListObjects à la fois dans la version 2 et la version 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";
    }
}

Les objets Paginator possèdent une search() méthode qui vous permet d'utiliser des JMESPathexpressions pour extraire plus facilement les données du jeu de résultats.

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

De nombreuses abstractions de niveau supérieur ont changé

En général, la plupart des abstractions de niveau supérieur (objets d'assistant spécifiques au service, hormis les clients) ont été améliorées ou mises à jour. Certaines ont été supprimées.

Comparaison d'échantillons de code provenant des deux versions du SDK

Les exemples suivants montrent en quoi l'utilisation de la version 3 AWS SDK for PHP peut différer de la version 2.

Exemple : ListObjects opération Amazon S3

À partir de la version 2 du 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";
}

À partir de la version 3 du SDK

Principales différences :

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

Exemple : Instanciation d'un Client avec une configuration globale

À partir de la version 2 du 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.

À partir de la version 3 du SDK

Principales différences :

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