Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Aggiornamento dalla versione 2 del AWS SDK for PHP

Questo argomento mostra come migrare il codice per utilizzare la versione 3 dell'AWS SDK for PHP e come la nuova versione differisce dalla versione 2 dell'SDK.

Introduzione

La versione 3 dell'AWS SDK for PHP rappresenta un notevole sforzo per migliorare le funzionalità dell'SDK, integrare più di due anni di feedback dei clienti, aggiornare le nostre dipendenze, migliorare le prestazioni e adottare i più recenti standard PHP.

Novità della versione 3

La versione 3 AWS SDK for PHP segue gli standard PSR-4 e PSR-7 e seguirà gli standard in futuro SemVer.

Altre nuove caratteristiche includono

Livello HTTP disassociato

Richieste asincrone

Cosa cambia rispetto alla versione 2

Le dipendenze di progetto sono aggiornate

Le dipendenze dell'SDK sono state modificate in questa versione.

Le opzioni di regione e versione (Region e Version) sono ora obbligatorie

Quando si creano istanze per un client per qualsiasi servizio, specificare le opzioni 'region' e 'version'. Nella versione 2 dell'AWS SDK for PHP, 'version' era completamente facoltativa e 'region'era talvolta facoltativa. Nella versione 3, entrambe le opzioni sono sempre obbligatorie. Essere espliciti su entrambe queste opzioni ti consente di bloccare la versione dell'API e la AWS regione in cui stai codificando. Quando vengono create nuove versioni API o diventano disponibili nuove AWS regioni, sarai isolato da eventuali modifiche non valide finché non sarai pronto ad aggiornare esplicitamente la tua configurazione.

L'istanza del client usa il costruttore

Nella versione 3 dell'AWS SDK for PHP, è stato modificato il modo in cui si creano le istanze di un client. Anziché utilizzare i metodi factory nella versione 2, è possibile creare con facilità un'istanza di un client utilizzando la parola chiave 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'
]);

La configurazione del client è stata modificata

Le opzioni di configurazione del client nella versione 3 dell'AWS SDK for PHP sono state leggermente modificate rispetto alla versione 2. Consulta la pagina Configurazione per la AWS SDK for PHP versione 3 per una descrizione di tutte le opzioni supportate.

L'oggetto Sdk

Nella versione 3 dell'AWS SDK for PHP viene introdotto l'oggetto Aws\Sdk come sostituto di Aws\Common\Aws. L'oggetto Sdk agisce come un client factory e viene utilizzato per gestire le opzioni di configurazione condivise da più client.

Anche se la classe Aws nella versione 2 dell'SDK funzionava come localizzatore di servizio (restituiva sempre la stessa istanza di un client), la classe Sdk nella versione 3 restituisce una nuova istanza di un client ogni volta che viene utilizzata.

L'oggetto Sdk, inoltre, non supporta lo stesso formato di file di configurazione dalla versione 2 dell'SDK. Questo formato di configurazione era specifico per Guzzle 3 ed è ora obsoleto. La configurazione può essere eseguita più semplicemente con gli array di base ed è documentata in Utilizzo della classe Sdk.

Alcuni risultati delle API sono cambiati

Per garantire coerenza nel modo in cui l'SDK analizza il risultato di un'operazione API, AmazonElastiCache, Amazon RDS e Amazon Redshift dispongono ora di un elemento di wrapping aggiuntivo su alcune risposte API.

Ad esempio, la chiamata del DescribeEngineDefaultParametersrisultato di Amazon RDS nella versione 3 ora include un elemento wrapping «EngineDefaults». Nella versione 2, questo elemento non era 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'];

Le seguenti operazioni sono interessate e ora contengono un elemento di wrapping nell'output del risultato (fornito di seguito tra parentesi):

Classi di enumerazione che sono state rimosse

Abbiamo rimosso le classi Enum (ad esempio, Aws\S3\Enum\CannedAcl) presenti nella versione 2 dell'AWS SDK for PHP. Le enumerazioni erano classi concrete all'interno dell'API pubblica dell'SDK che conteneva costanti che rappresentano gruppi di validità i valori dei parametri. Poiché queste enumerazioni sono specifiche per le versioni dell'API, possono cambiare nel tempo, possono entrare in conflitto con parole riservate PHP e non sono risultate molto utili, le abbiamo rimosse nella versione 3. Questo supporta la natura agnostica della versione API basato su dati della versione 3.

Invece di utilizzare i valori di oggetti Enum, utilizza i valori letterali direttamente (ad esempio CannedAcl::PUBLIC_READ → 'public-read').

Classi di eccezioni granulari sono state rimosse

Abbiamo rimosso le classi di eccezione granulari esistenti negli spazi dei nomi di ciascun servizio (ad esempio, Aws\Rds\Exception\{SpecificError}Exception) per motivi molto simili a quelli per cui abbiamo rimosso le enumerazioni. Le eccezioni generate da un servizio o operazione dipendono da quale versione dell'API viene utilizzata (possono variare da una versione all'altra). Inoltre, l'elenco completo delle eccezioni che possono essere generate da una determinata operazione non è disponibile, il che rendeva le classi di eccezione granulari della versione 2 incomplete.

Gestire gli errori ricevendo la classe di eccezione root per ciascun servizio (ad esempio, Aws\Rds\Exception\RdsException). È possibile utilizzare il metodo di eccezione getAwsErrorCode() per verificare la presenza di codici di errore specifici. Questo è funzionalmente equivalente a catturare diverse classi di eccezioni, ma prevede che funzionino senza aggiungere dimensioni all'SDK.

Le classi Facade statiche sono state rimosse

Nella versione 2 dell'AWS SDK for PHP, era presente una caratteristica oscura ispirata da Laravel che consentiva di chiamare enableFacades() sulla classe Aws per abilitare l'accesso ai vari servizi client. Questa caratteristica va contro le best practice di PHP e abbiamo smesso di documentarla più di un anno fa. Nella versione 3, questa caratteristica è stata completamente rimossa. Recuperare gli oggetti client dall'oggetto Aws\Sdk e utilizzarli come istanze di oggetti, non classi statiche.

Gli impaginatori sostituiscono gli iteratori

La versione 2 dell'AWS SDK for PHP aveva una funzionalità denominata *iteratori*. Questi oggetti sono stati utilizzati per reiterare i risultati impaginati in modo eccessivo. Un reclamo che abbiamo ricevuto su questi oggetti era che non erano sufficientemente flessibili, perché l'iteratore emetteva solo valori specifici da ciascun risultato. Se avevi bisogno di altri valori dai risultati, potevi recuperarli solo tramite listener di eventi.

Nella versione 3, gli iteratori sono stati sostituiti con Impaginatori. Lo scopo è simile, ma gli impaginatori sono più flessibili. Questo è dovuto al fatto che restituiscono gli oggetti di risultato anziché i valori da una risposta.

I seguenti esempi mostrano come gli impaginatori differiscono dagli iteratori, dimostrando come recuperare i risultati impaginati per l'operazione S3 ListObjects sia nella versione 2 che nella versione 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";
    }
}

Gli oggetti impaginatore dispongono di un metodo search() che consente di utilizzare espressioni JMESPath per estrarre i dati in modo più semplice dal set di risultati.

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

Molte astrazioni di livello più elevato sono cambiate

In generale, molte delle astrazioni di livello più elevato (oggetti helper specifici per il servizio, tranne i client) sono state migliorate o aggiornate. Alcune sono state rimosse.

Confronto tra gli esempi di codice da parte di entrambe le versioni dell'SDK

I seguenti esempi mostrano alcuni dei modi in cui l'utilizzo della versione 3 dell'AWS SDK for PHP potrebbe differire dalla versione 2.

Esempio: funzionamento di Amazon S3 ListObjects

Dalla versione 2 dell'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";
}

Dalla versione 3 dell'SDK

Differenze principali:

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

Esempio: creazione di un'istanza di un client con configurazione globale

Dalla versione 2 dell'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.

Dalla versione 3 dell'SDK

Differenze principali:

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