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.
# Migration depuis la version 2 du AWS SDK pour PHP
Cette rubrique montre comment migrer votre code pour utiliser la version 3 du kit AWS SDK pour PHP et ce en quoi la nouvelle version diffère de la version 2 du kit SDK.
**Note**
Le modèle d'utilisation de base du kit SDK (par exemple, `$result = $client->operation($params);`) n'a pas changé entre la version 2 et la version 3, ce qui devrait aboutir à une migration transparente.
## Introduction
La version 3 du AWS SDK pour PHP représente un effort important pour améliorer les fonctionnalités du SDK, intégrer plus de deux ans de commentaires clients, mettre à niveau nos dépendances, améliorer les performances et adopter les dernières normes PHP.
## Quoi de neuf dans la version 3 ?
La version 3 AWS SDK pour PHP suit les normes [PSR-4 et PSR-7 et suivra la norme](http://php-fig.org) à l'[SemVer](http://semver.org/)avenir.
Parmi les autres nouvelles fonctionnalités, citons :
+ Système Middleware pour personnaliser le comportement du client de service
+ *Programmes de pagination* flexibles pour l’itération sur les résultats paginés
+ Possibilité d'interroger des données à partir d'objets de *résultat* et de *paginateur* avec *JMESPath*
+ Débogage facile via l'option de configuration `'debug'`
### Couche HTTP découplée
+ [Guzzle 6](http://guzzlephp.org) est utilisé par défaut pour envoyer des demandes, mais Guzzle 5 est également pris en charge.
+ Le kit SDK fonctionne dans les environnements où cURL n'est pas disponible.
+ Les gestionnaires HTTP personnalisés sont également pris en charge.
### Requêtes asynchrones
+ Des fonctions telles que les *programmes d’attente* et le *chargement partitionné* peuvent également être utilisées de manière asynchrone.
+ Il est possible de créer des workflows asynchrones à l’aide de *promesses* et *coroutines*.
+ Les performances des demandes simultanées ou par lots sont améliorées.
## Qu'est-ce qui est différent de la version 2 ?
### Les dépendances du projet sont mises à jour
Les dépendances du kit SDK ont été modifiées dans cette version.
+ Le SDK nécessite désormais PHP 8.1\$1. Nous utilisons abondamment les [générateurs](http://php.net/manual/en/language.generators.overview.php) dans le code de kit SDK.
+ Nous avons mis à niveau le SDK pour utiliser [Guzzle 6](http://guzzlephp.org) (ou 5), qui fournit l'implémentation du client HTTP sous-jacent utilisé par le SDK pour envoyer des requêtes aux services. AWS La dernière version de Guzzle amène un certain nombre d'améliorations, y compris les demandes asynchrones, les gestionnaires HTTP interchangeables, la conformité à PSR 7, de meilleures performances, et bien plus encore.
+ Le package PSR-7 de PHP-FIG (`psr/http-message`) définit des interfaces pour représenter les requêtes HTTP, les réponses HTTP et les flux. URLs Ces interfaces sont utilisées dans le kit SDK et Guzzle, qui fournit l'interopérabilité avec d'autres packages conformes à PSR-7.
+ L'implémentation par Guzzle de PSR-7 (`guzzlehttp/psr7`) fournit une implémentation des interfaces dans PSR-7, et plusieurs classes et fonctions utiles. Le kit SDK et Guzzle 6 s'appuient fortement sur ce package.
+ L'implémentation des [promesses/A\$1](https://promisesaplus.com) de Guzzle (`guzzlehttp/promises`) est utilisée dans le kit SDK et Guzzle afin de fournir des interfaces pour la gestion des demandes et coroutines asynchrones. Alors que le gestionnaire HTTP multi-CURL de Guzzle implémente finalement le I/O modèle non bloquant qui permet les requêtes asynchrones, ce package permet de programmer selon ce paradigme. Voir [Promises dans la AWS SDK pour PHP version 3](guide_promises.md) pour plus de détails.
+ L'implémentation PHP de [JMESPath](http://jmespath.org/)(`mtdowling/jmespath.php`) est utilisée dans le SDK pour fournir la capacité d'interrogation de données des méthodes `Aws\Result::search()` and`Aws\ResultPaginator::search()`. Voir [JMESPath Expressions dans la AWS SDK pour PHP version 3](guide_jmespath.md) pour plus de détails.
### Les options de région et de version sont désormais 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 pour PHP, `'version'` était totalement optionnel, et `'region'` était parfois facultatif. Dans la version 3, les deux sont toujours requis. Le fait d'indiquer clairement ces deux options vous permet de vous connecter à la version de l'API et à AWS la région dans 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.
**Note**
Si vous ne savez pas quelle version d'API vous utilisez, vous pouvez définir l'option `'version'` sur `'latest'`. Cependant, nous vous recommandons de définir les numéros de version d'API de façon explicite pour le code de production.
Les services ne sont pas tous disponibles dans toutes les AWS régions. Pour connaître la liste des régions disponibles, consultez le document de référence [Régions et points de terminaison](https://docs.aws.amazon.com/general/latest/gr/rande.html).
Pour les services disponibles uniquement via un seul point de terminaison global (par exemple, Amazon Route 53 et Amazon CloudFront) Gestion des identités et des accès AWS, instanciez les clients avec leur région configurée définie sur. `us-east-1`
**Important**
Le SDK inclut également des clients multirégionaux, qui peuvent envoyer des demandes à différentes AWS régions en fonction d'un paramètre (`@region`) fourni en tant que paramètre de commande. La région utilisée par défaut par ces clients est spécifiée avec l'option `region` fournie au constructeur client.
### L'instanciation du client utilise le constructeur
Dans la version 3 de AWS SDK pour 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'
]);
```
**Note**
L'instanciation d'un client à l'aide de la méthode `factory()` fonctionne toujours. Cependant, elle est considérée comme obsolète.
### La configuration du client a changé
Les options de configuration du client dans la version 3 du AWS SDK pour PHP ont légèrement changé par rapport à la version 2. Consultez la page [Configuration pour la AWS SDK pour PHP version 3](guide_configuration.md) pour une description de toutes les options prises en charge.
**Important**
Dans la version 3, les options `'key'` et `'secret'` ne sont plus valides au niveau de la racine, mais vous pouvez les transmettre dans le cadre de l'option `'credentials'`. L'une des raisons pour lesquelles nous l'avons fait était de décourager les développeurs de coder en dur leurs AWS informations d'identification dans leurs projets.
#### L'objet Sdk
La version 3 de AWS SDK pour PHP introduit l'`Aws\Sdk`objet 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](configuring-service-clients-code.md#sdk-class).
### Certains résultats de l'API ont changé
Pour garantir la cohérence de la manière dont le SDK analyse le résultat d'une opération d'API, Amazon, Amazon RDS et ElastiCache Amazon Redshift disposent désormais d'un élément d'encapsulation supplémentaire sur certaines réponses d'API.
Par exemple, l'appel du [DescribeEngineDefaultParameters](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeEngineDefaultParameters.html)résultat Amazon RDS dans la version 3 inclut désormais un élément d'encapsulage « 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) :
+ Amazon ElastiCache
+ AuthorizeCacheSecurityGroupIngress (CacheSecurityGroup)
+ CopySnapshot (Instantané)
+ CreateCacheCluster (CacheCluster)
+ CreateCacheParameterGroup (CacheParameterGroup)
+ CreateCacheSecurityGroup (CacheSecurityGroup)
+ CreateCacheSubnetGroup (CacheSubnetGroup)
+ CreateReplicationGroup (ReplicationGroup)
+ CreateSnapshot (Instantané)
+ DeleteCacheCluster (CacheCluster)
+ DeleteReplicationGroup (ReplicationGroup)
+ DeleteSnapshot (Instantané)
+ DescribeEngineDefaultParameters (EngineDefaults)
+ ModifyCacheCluster (CacheCluster)
+ ModifyCacheSubnetGroup (CacheSubnetGroup)
+ ModifyReplicationGroup (ReplicationGroup)
+ PurchaseReservedCacheNodesOffering (ReservedCacheNode)
+ RebootCacheCluster (CacheCluster)
+ RevokeCacheSecurityGroupIngress (CacheSecurityGroup)
+ Amazon RDS
+ AddSourceIdentifierToSubscription (EventSubscription)
+ Autoriser DBSecurity GroupIngress (DBSecuritygroupe)
+ Copier DBParameter un groupe (DBParameterGroupe)
+ Copier DBSnapshot (DBSnapshot)
+ CopyOptionGroup (OptionGroup)
+ Créer DBInstance (DBInstance)
+ Créer DBInstance ReadReplica (DBInstance)
+ Créer un DBParameter groupe (DBParameterGroupe)
+ Créer un DBSecurity groupe (DBSecurityGroupe)
+ Créer DBSnapshot (DBSnapshot)
+ Créer un DBSubnet groupe (DBSubnetGroupe)
+ CreateEventSubscription (EventSubscription)
+ CreateOptionGroup (OptionGroup)
+ Supprimer DBInstance (DBInstance)
+ Supprimer DBSnapshot (DBSnapshot)
+ DeleteEventSubscription (EventSubscription)
+ DescribeEngineDefaultParameters (EngineDefaults)
+ Modifier DBInstance (DBInstance)
+ Modifier DBSubnet le groupe (DBSubnetgroupe)
+ ModifyEventSubscription (EventSubscription)
+ ModifyOptionGroup (OptionGroup)
+ PromoteReadReplica (DBInstance)
+ PurchaseReservedDBInstancesOffre (réservéeDBInstance)
+ Redémarrer DBInstance (DBInstance)
+ RemoveSourceIdentifierFromSubscription (EventSubscription)
+ Restaurer DBInstance depuis DBSnapshot (DBInstance)
+ Restaurer DBInstance ToPointInTime (DBInstance)
+ Révoquer DBSecurity GroupIngress (DBSecuritygroupe)
+ Amazon Redshift
+ AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup)
+ AuthorizeSnapshotAccess (Instantané)
+ CopyClusterSnapshot (Instantané)
+ CreateCluster (Cluster)
+ CreateClusterParameterGroup (ClusterParameterGroup)
+ CreateClusterSecurityGroup (ClusterSecurityGroup)
+ CreateClusterSnapshot (Instantané)
+ CreateClusterSubnetGroup (ClusterSubnetGroup)
+ CreateEventSubscription (EventSubscription)
+ CreateHsmClientCertificate (HsmClientCertificate)
+ CreateHsmConfiguration (HsmConfiguration)
+ DeleteCluster (Cluster)
+ DeleteClusterSnapshot (Instantané)
+ DescribeDefaultClusterParameters (DefaultClusterParameters)
+ DisableSnapshotCopy (Cluster)
+ EnableSnapshotCopy (Cluster)
+ ModifyCluster (Cluster)
+ ModifyClusterSubnetGroup (ClusterSubnetGroup)
+ ModifyEventSubscription (EventSubscription)
+ ModifySnapshotCopyRetentionPeriod (Cluster)
+ PurchaseReservedNodeOffering (ReservedNode)
+ RebootCluster (Cluster)
+ RestoreFromClusterSnapshot (Cluster)
+ RevokeClusterSecurityGroupIngress (ClusterSecurityGroup)
+ RevokeSnapshotAccess (Instantané)
+ RotateEncryptionKey (Cluster)
### Les classes Enum ont été supprimées
Nous avons supprimé les classes `Enum` (par exemple, `Aws\S3\Enum\CannedAcl`) qui existaient dans la version 2 du kit AWS SDK pour 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 d'exception détaillées 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 statiques ont été supprimées
Dans la version 2 du AWS SDK pour 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 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 paginateurs remplacent les itérateurs
La version 2 de AWS SDK pour PHP avait une fonctionnalité nommée \$1 iterators\$1. 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](guide_paginators.md). 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 [JMESPath](guide_jmespath.md)expressions 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";
}
```
**Note**
La méthode `getIterator()` est toujours prise en charge pour permettre une transition en douceur vers la version 3, mais nous vous encourageons à migrer votre code pour permettre l'utilisation des programmes de pagination.
### De nombreuses abstractions de haut niveau 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.
+
**Mis à jour:**
+ La façon d’utiliser la [fonction de chargement partitionné Amazon S3](s3-multipart-upload.md) a changé. Le téléchargement partitionné sur Amazon Glacier a été modifié de la même manière.
+ La façon de créer une version [pré-signée d'Amazon S3 URLs](s3-presigned-url.md) a changé.
+ L'espace de noms `Aws\S3\Sync` a été remplacé par la classe `Aws\S3\Transfer`. Les méthodes `S3Client::uploadDirectory()` et `S3Client::downloadBucket()` sont toujours disponibles, mais présentent des options différentes. Consultez la documentation d'[Amazon S3 Transfer Manager AWS SDK pour PHP version 3](s3-transfer.md).
+ `Aws\S3\Model\ClearBucket` et `Aws\S3\Model\DeleteObjectsBatch` ont été remplacés par `Aws\S3\BatchDelete` et `S3Client::deleteMatchingObjects()`.
+ Les options et les comportements relatifs à l'[utilisation du gestionnaire de session DynamoDB AWS SDK pour PHP avec la version](service_dynamodb-session-handler.md) 3 ont légèrement changé.
+ L'espace de noms `Aws\DynamoDb\Model\BatchRequest` a été remplacé par `Aws\DynamoDb\WriteRequestBatch`. Consultez la documentation de [DynamoDB WriteRequestBatch](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.DynamoDb.WriteRequestBatch.html).
+ Le `Aws\Ses\SesClient` gère désormais l'encodage base64 pour le `RawMessage` lors de l'utilisation de l'opération `SendRawEmail`.
+
**Supprimés :**
+ [Amazon `Item` DynamoDB`Attribute`,, `ItemIterator` et classes : elles étaient auparavant obsolètes dans la version 2.7.0.](https://github.com/aws/aws-sdk-php/blob/3.0.0/CHANGELOG.md#270===2014-10-08)
+ Validateur de messages Amazon SNS : il s'agit désormais [d'un projet distinct et léger](https://github.com/aws/aws-php-sns-message-validator) qui ne nécessite pas le SDK comme dépendance. Ce projet est, toutefois, inclus dans les distributions Phar et ZIP du kit SDK. Vous trouverez un guide de démarrage [sur le blog de développement AWS PHP](https://aws.amazon.com/blogs/developer/receiving-amazon-sns-messages-in-php/).
+ Amazon S3 `AcpBuilder` et les objets associés ont été supprimés.
## Comparaison d'échantillons de code provenant des deux versions du SDK
Les exemples suivants montrent en quoi l'utilisation de la version 3 de est AWS SDK pour PHP différente de la version 2.
### Exemple : `ListObjects` opération Amazon S3
#### À partir de la version 2 du SDK
```
'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 :
+ Utilisation de `new` au lieu de `factory()` pour instancier le client.
+ Les options `'version'` et `'region'` sont requises durant l'instanciation.
```
'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
```
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'
)
),
)
);
```
```
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 :
+ Utilisation de la classe `Aws\Sdk` au lieu de la classe `Aws\Common\Aws`.
+ Il n'y a pas de fichier de configuration. À la place, utilisation d'un tableau pour la configuration.
+ L'option `'version'` est requise durant l'instanciation.
+ Utilisation des méthodes `create()` au lieu de la méthode `get('')`.
```
'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.
```