Amazon VGT2 Las Vegas: Version 3 of the AWS SDK for PHP

More Info

Last October, we introduced the Developer Preview of Version 3 of the AWS SDK for PHP. Our presentation at AWS re:Invent last November received positive feedback, and we appreciate your support. Since then, we have dedicated ourselves to refining, testing, and documenting Version 3 to prepare for its stable release. We are thrilled to announce that Version 3 of the AWS SDK for PHP is now generally available via Composer and on GitHub.

The release of Version 3 (V3) represents a substantial effort to enhance the SDK’s capabilities, incorporate over two years of user feedback, upgrade dependencies, boost performance, and embrace the latest PHP standards.

Highlights of Version 3

We have made numerous enhancements to V3 since our initial Developer Preview blog post—if you haven’t seen it yet, it’s worth checking out another blog post on the subject. There have also been changes and removals compared to Version 2 (V2). We recommend reviewing our V3 Migration Guide for comprehensive details on these changes.

V3 features streamlined code and improved performance, utilizing the latest version of the Guzzle HTTP library. Furthermore, it introduces exciting new functionalities.

Asynchronous Requests and Promises

With V3, you can perform operations asynchronously. This makes concurrent requests simpler and allows for the creation of asynchronous and cooperative workflows. Promises, the core component of our asynchronous features, are extensively used throughout the SDK. They facilitate the implementation of higher-level abstractions, including Command Pools, Paginators, Waiters, and service-specific capabilities like the S3 MultipartUploader. Almost every SDK feature can now be employed asynchronously.

To execute an operation asynchronously, simply append “Async” to your method call:

// The SYNCHRONOUS (normal) way:
$result = $s3Client->putObject([
    'Bucket' => 'your-bucket',
    'Key'    => 'docs/file.pdf',
    'Body'   => fopen('/path/to/file.pdf', 'r'),
]);
echo $result['ObjectURL'];

// The ASYNCHRONOUS way:
$promise = $s3Client->putObjectAsync([
    'Bucket' => 'your-bucket',
    'Key'    => 'docs/file.pdf',
    'Body'   => fopen('/path/to/file.pdf', 'r'),
]);
$result = $promise->wait();
echo $result['ObjectURL'];

The true strength of using asynchronous requests lies in creating complex workflows. For instance, to create a DynamoDB table, wait until it becomes ACTIVE (using Waiters), and then insert data, you can chain these actions using the then() method of the Promise object.

$client->createTableAsync([
    'TableName' => $table,
    // Other params...
])->then(function () use ($client, $table) {
    return $client->getWaiter('TableExists', [
        'TableName' => $table,
    ])->promise();
})->then(function () use ($client, $table) {
    return $client->putItemAsync([
        'TableName' => $table,
        'Item' => [
            // Item attributes...
        ]
    ]);
})->wait();

For further information, please refer to our detailed guide on promises.

PSR-7 Compliance and HTTP Layer Decoupling

The PHP-FIG recently approved PSR-7, which defines interfaces for HTTP messages (such as Request and Response objects). We have integrated these interfaces into how the SDK represents HTTP requests, enabling us to decouple it from Guzzle. Consequently, V3 is compatible with both Guzzle 5 and Guzzle 6. You can also create your own HTTP handler for the SDK that does not rely on Guzzle.

By default, the SDK uses Guzzle 6 for HTTP requests, which includes several enhancements, such as support for asynchronous requests, PSR-7 compliance, and interchangeable HTTP adapters (including a PHP stream wrapper for environments without cURL).

JMESPath Querying of Results and Paginators

In V3, the Result object introduces a new method: search(). This method allows you to query data in Result objects using JMESPath expressions, a query language tailored for JSON, or in our case, PHP arrays.

$result = $ec2Client->describeInstances();
print_r($result->search('Reservations[].Instances[].InstanceId'));

JMESPath expressions can also be utilized with Paginators similarly, yielding a new Iterator that applies the expression across every data page.

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

Time to Code

We hope you enjoy using Version 3 of the AWS SDK for PHP. For a comprehensive start, here are essential links:

• User Guide Documentation
• API Documentation
• GitHub Repository

Stay connected by following @awsforphp on Twitter for updates!