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 montre comment migrer votre code pour utiliser la version 3 du kit AWS SDK for PHP et ce en quoi la nouvelle version diffère de la version 2 du kit SDK.

Introduction

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

Nouveautés de la version 3

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

Les autres nouvelles fonctions sont les suivantes :

Couche HTTP découplée

Requêtes asynchrones

Changements par rapport à la version 2

Dépendances du projet mises à jour

Les dépendances du kit SDK ont été modifiées 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 kit AWS SDK for PHP, 'version' était entièrement facultatif et 'region' était parfois facultatif. Dans la version 3, les deux sont toujours requis. Le fait d'être explicite à propos de ces deux options vous permet de vous limiter à la version de l'API et à AWS la région sur lesquelles vous codez. Lorsque de nouvelles versions d'API 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 du kit 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 kit AWS SDK for PHP ont légèrement changé par rapport à la version 2. Consultez la page Configuration de la AWS SDK for PHP version 3 pour obtenir une description de toutes les options prises en charge.

L'objet Sdk

La version 3 du kit AWS SDK for PHP introduit l’objet Aws\Sdk en remplacement de Aws\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 classe Aws dans la version 2 du kit SDK fonctionnait comme un localisateur de service (il retournait toujours la même instance d'un client), la classe Sdk dans la version 3 renvoie une nouvelle instance d'un client à chaque fois qu'elle est utilisée.

De plus, l'objet Sdk ne prend pas en charge le même format de fichier de configuration à partir de la version 2 du kit SDK. 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 résultats d'API ont changé

Pour assurer la cohérence de la manière dont le SDK analyse le résultat d'une opération d'APIElastiCache, Amazon RDS et Amazon Redshift disposent désormais d'un élément d'encapsulation supplémentaire pour certaines réponses d'API.

Par exemple, l'appel du DescribeEngineDefaultParametersrésultat Amazon RDS dans la version 3 inclut désormais un élément d'encapsulation « 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. Enums étaient des classes concrètes au sein de l'API public du kit SDK qui contenaient des constantes représentant des groupes de valeurs de paramètre valides. Etant donné que les Enums sont spécifiques aux versions d'API, peuvent changer au fil du temps, créer des conflits avec les mots réservés PHP, et n'étaient finalement pas très utiles, nous les avons supprimées dans la version 3. Cela va dans le sens de la nature souple concernant l'exploitation des données et la version d'API 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 version d'API qui est 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. Cette fonctionnalité est équivalente à celle de l'interception de différentes classes d'exception, mais fournit cette fonction sans ajouter la distension au kit SDK.

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

Dans la version 2 du kit AWS SDK for PHP, une fonction obscure inspirée par Laravel vous permettait d’appeler enableFacades() sur la classe Aws pour activer l’accès statique aux différents clients de service. Cette fonction est contraire aux bonnes pratiques PHP, et nous avons arrêté 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 du kit AWS SDK for PHP comprenait une fonction nommée *itérateurs*. 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' => 'my-bucket']);
foreach ($objects as $object) {
    echo $object['Key'] . "\n";
}

// Version 3
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-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 de programme de pagination disposent d’une méthode search() qui vous permet d’utiliser des expressions JMESPath pour extraire des données plus facilement à partir de l’ensemble de résultats.

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-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'exemples de code à partir de deux versions du kit SDK

Les exemples suivants illustrent certaines façons dont l'utilisation de la version 3 du kit AWS SDK for PHP peut différer de la version 2.

Exemple : ListObjects opération Amazon S3

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' => 'my-bucket-name',
        'Key'    => 'my-object-key'
    ]);

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

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' => 'my-bucket-name',
        '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

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.

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.