Upgrade from Version 2 of the AWS SDK for PHP

This topic shows how to migrate your code to use version 3 of the AWS SDK for PHP and how the new version differs from version 2 of the SDK.

Introduction

Version 3 of the AWS SDK for PHP represents a significant effort to improve the capabilities of the SDK, incorporate over two years of customer feedback, upgrade our dependencies, improve performance, and adopt the latest PHP standards.

What’s New in Version 3?

Version 3 of the AWS SDK for PHP follows the PSR-4 and PSR-7 standards and will follow the SemVer standard going forward.

Other new features include

Decoupled HTTP layer

Asynchronous requests

What’s Different from Version 2?

Project Dependencies are Updated

The dependencies of the SDK have changed in this version.

Region and Version Options Are Now Required

When instantiating a client for any service, specify the 'region' and 'version' options. In version 2 of the AWS SDK for PHP, 'version' was completely optional, and 'region' was sometimes optional. In version 3, both are always required. Being explicit about both of these options allows you to lock into the API version and AWS Region you are coding against. When new API versions are created or new AWS Regions become available, you will be isolated from potentially breaking changes until you are ready to explicitly update your configuration.

Client Instantiation Uses the Constructor

In version 3 of the AWS SDK for PHP, the way you instantiate a client has changed. Instead of the factory methods in version 2, you can simply instantiate a client by using the new keyword.

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

Client Configuration Has Changed

The client configuration options in version 3 of the AWS SDK for PHP have changed a little from version 2. See the Configuration for the AWS SDK for PHP Version 3 page for a description of all supported options.

The Sdk Object

Version 3 of the AWS SDK for PHP introduces the Aws\Sdk object as a replacement to Aws\Common\Aws. The Sdk object acts as a client factory and is used to manage shared configuration options across multiple clients.

Although the Aws class in version 2 of the SDK worked like a service locator (it always returned the same instance of a client), the Sdk class in version 3 returns a new instance of a client every time it’s used.

The Sdk object also doesn’t support the same configuration file format from version 2 of the SDK. That configuration format was specific to Guzzle 3 and is now obsolete. Configuration can be done more simply with basic arrays, and is documented in Using the Sdk Class.

Some API Results Have Changed

To provide consistency in how the SDK parses the result of an API operation, Amazon ElastiCache, Amazon RDS, and Amazon Redshift now have an additional wrapping element on some API responses.

For example, calling the Amazon RDSDescribeEngineDefaultParameters result in version 3 now includes a wrapping “EngineDefaults” element. In version 2, this element was not present.

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

The following operations are affected and now contain a wrapping element in the output of the result (provided below in parentheses):

Enum Classes Have Been Removed

We have removed the Enum classes (e.g., Aws\S3\Enum\CannedAcl) that existed in version 2 of the AWS SDK for PHP. Enums were concrete classes within the public API of the SDK that contained constants representing groups of valid parameter values. Because these enums are specific to API versions, can change over time, can conflict with PHP reserved words, and ended up not being very useful, we have removed them in version 3. This supports the data-driven and API version agnostic nature of version 3.

Instead of using values from Enum objects, use the literal values directly (e.g., CannedAcl::PUBLIC_READ → 'public-read').

Fine-Grained Exception Classes Have Been Removed

We have removed the fine-grained exception classes that existed in each service’s namespaces (e.g., Aws\Rds\Exception\{SpecificError}Exception) for very similar reasons that we removed Enums. The exceptions thrown by a service or operation are dependent on which API version is used (they can change from version to version). Also, the complete list of the exceptions that can be thrown by a given operation is not available, which made version 2’s fine-grained exception classes incomplete.

Handle errors by catching the root exception class for each service (e.g., Aws\Rds\Exception\RdsException). You can use the getAwsErrorCode() method of the exception to check for specific error codes. This is functionally equivalent to catching different exception classes, but provides that function without adding bloat to the SDK.

Static Facade Classes Have Been Removed

In version 2 of the AWS SDK for PHP, there was an obscure feature inspired by Laravel that allowed you to call enableFacades() on the Aws class to enable static access to the various service clients. This feature goes against PHP best practices, and we stopped documenting it over a year ago. In version 3, this feature is removed completely. Retrieve your client objects from the Aws\Sdk object and use them as object instances, not static classes.

Paginators Supersede iterators

Version 2 of the AWS SDK for PHP had a feature named * iterators*. These were objects that were used for iterating over paginated results. One complaint we had about these was that they were not flexible enough, because the iterator only emitted specific values from each result. If there were other values you needed from the results, you could only retrieve them via event listeners.

In version 3, iterators have been replaced with Paginators. Their purpose is similar, but paginators are more flexible. This is because they yield result objects instead of values from a response.

The following examples show how paginators are different from iterators, by demonstrating how to retrieve paginated results for the S3 ListObjects operation in both version 2 and 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";
    }
}

Paginator objects have a search() method that enables you to use JMESPath expressions to extract data more easily from the result set.

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

Many Higher-Level Abstractions Have Changed

In general, many of the higher-level abstractions (service-specific helper objects, aside from the clients) have been improved or updated. Some have even been removed.

Comparing Code Samples from Both Versions of the SDK

The following examples show some of the ways in which using version 3 of the AWS SDK for PHP might differ from version 2.

Example: Amazon S3 ListObjects Operation

From Version 2 of the 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";
}

From Version 3 of the SDK

Key differences:

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

Example: Instantiating a Client with global Configuration

From Version 2 of the 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.

From Version 3 of the SDK

Key differences:

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