Basic SDK Usage

This guide focuses on basic usage patterns of the AWS SDK for PHP. This guide assumes that you have already downloaded and installed the SDK and retrieved your AWS access keys.

Including the SDK

No matter which technique you have used to to install the SDK, you can include the SDK into your code with just a single require statement. Please refer to the following table for the PHP code that best fits your installation technique. Please replace any instances of /path/to/ with the actual path on your system.

Installation Technique	Require Statement
Using Composer	require '/path/to/vendor/autoload.php';
Using the Phar	require '/path/to/aws.phar';
Using the Zip	require '/path/to/aws-autoloader.php';

For the remainder of this guide, we will show examples that assume the Composer installation method. If you are using a different installation method, then you can refer back to this section to substitute in the proper require code.

Usage Summary

The basic usage pattern of the SDK is that you instantiate a Client object for the AWS service you want to interact with. Client objects have methods that correspond one-to-one with operations in the service's API. To execute a particular operation, you call its corresponding method, which either returns an array-like Result object on success, or throws an Exception on failure.

Creating a client

You can create a client by passing an associative array of options to a client's constructor.

<?php
// Include the SDK using the Composer autoloader
require 'vendor/autoload.php';

$s3 = new Aws\S3\S3Client([
    'version' => 'latest',
    'region'  => 'us-east-1'
]);

Notice that we did not explicitly provide credentials to the client. That's because the credentials should be detected by the SDK from either environment variables (via AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY), an AWS credentials INI file in your HOME directory, AWS Identity and Access Management (IAM) instance profile credentials, or credential providers.

All of the general client configuration options are described in detail in the configuration guide. The array of options provided to a client may vary based on which client you are creating. These custom client configuration options are described in the API documentation of each client.

Using the Sdk class

The Aws\Sdk class acts as a client factory and is used to manage shared configuration options across multiple clients. The same options that can be provided to a specific client constructor can also be supplied to the Aws\Sdk class. These options are then applied to each client constructor.

// Use the us-west-2 region and latest version of each client.
$sharedConfig = [
    'region'  => 'us-west-2',
    'version' => 'latest'
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Create an Amazon S3 client using the shared configuration data.
$client = $sdk->createS3();

Options that are shared across all clients are placed in root-level key-value pairs. Service-specific configuration data can be provided in a key that is the same as the namespace of a service (e.g., "S3", "DynamoDb", etc.).

$sdk = new Aws\Sdk([
    'region'   => 'us-west-2',
    'version'  => 'latest',
    'DynamoDb' => [
        'region' => 'eu-central-1'
    ]
]);

// Creating a DynamoDb client will use the "eu-central-1" region.
$client = $sdk->createDynamoDb();

Service-specific configuration values are a union of the service-specific values and the root-level values (i.e., service-specific values are shallow-merged onto root level values).

Tip

It is highly recommended that you use the Sdk class to create clients if you are utilizing multiple client instances in your application. The Sdk class will automatically utilize the same HTTP client for each SDK client, allowing SDK clients for different services to perform non-blocking HTTP requests. If the SDK clients do not use the same HTTP client, then HTTP requests sent by the SDK client may cause inter-service promise orchestration to block.

Executing service operations

You can execute a service operation by calling the method of the same name on a client object. For example, to perform the Amazon S3 PutObject operation, you must call the Aws\S3\S3Client::putObject() method.

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

// Send a PutObject request and get the result object.
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!'
]);

// Download the contents of the object.
$result = $s3Client->getObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'my-key'
]);

// Print the body of the result by indexing into the result object.
echo $result['Body'];

Operations available to a client and the structure of the input and output are defined at runtime based on a service description file. When creating a client, you must provide a version (e.g., "2006-03-01" or "latest"). The SDK will find the corresponding configuration file based on the provided version.

Operation methods like putObject() all accept a single argument -- an associative array representing the parameters of the operation. The structure of this array (and the structure of the result object) is defined for each operation in the SDK's API Documentation (e.g., see the API docs for putObject operation).

HTTP Handler Options

It's also possible to fine tune how the underlying HTTP handler executes the request by using the special @http parameter. The options you can include in the @http parameter are the same as the ones you can set when you instantiate the client with the "http" client option.

// Send the request through a proxy.
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

Asynchronous Requests

You can send commands concurrently using the asynchronous features of the SDK. You can send requests asynchronously by suffixing an operation name with Async. This will initiate the request and return a promise. The promise will be fulfilled with the result object on success or rejected with an exception on failure. This allows you to create multiple promises and have them send HTTP requests concurrently when the underlying HTTP handler transfers the requests.

$promise = $s3Client->listBucketsAsync();
// Block until the result is ready.
$result = $promise->wait();

You can force a promise to complete synchronously using the wait method of the promise. Forcing the promise to complete will also "unwrap" the state of the promise by default, meaning it will either return the result of the promise or throw the exception that was encountered. When calling wait() on a promise, the process will block until the HTTP request has completed and the result has been populated or an exception is thrown.

When using the SDK with an event loop library, you will not want to block on results, but rather use the then() method of a result to access a promise that is resolved or rejected when the operation completes.

$promise = $s3Client->listBucketsAsync();
$promise
    ->then(function ($result) {
        echo 'Got a result: ' . var_export($result, true);
    })
    ->otherwise(function ($reason) {
        echo 'Encountered an error: ' . $reason->getMessage();
    });

Working with Result objects

Executing an successful operation will return an Aws\Result object. Instead of returning the raw XML or JSON data of a service, the SDK coerces the response data into an associative array structure and normalizes some aspects of the data based on its knowledge of the specific service and the underlying response structure.

You can access data from the result object like an associative PHP array.

// Use an Aws\Sdk class to create the S3Client object.
$s3 = $sdk->createS3();
$result = $s3->listBuckets();

foreach ($result['Buckets'] as $bucket) {
    echo $bucket['Name'] . "\n";
}

// Convert the result object to a PHP array
$array = $result->toArray();

The contents of the result object depends on the operation that was executed and the version of a service. The result structure of each API operation is documented in the API docs for each operation.

The SDK is integrated with JMESPath, a DSL use to search and manipulate JSON data, or PHP arrays, in our case. The result object contains a search() method that allows you to more declaratively extract data from the result.

$s3 = $sdk->createS3();
$result = $s3Client->listBuckets();
// Get the name of each bucket
$results = $result->search('Buckets[].Name');

Handling errors

Synchronous Error Handling

If an error occurs while performing an operation, then an exception is thrown. For this reason, you should use try/catch blocks around your operations if you need to handle errors in your code. The SDK throws service-specific exceptions when an error occurs.

In the following example, the Aws\S3\S3Client is used. If there is an error, the exception thrown will be of the type Aws\S3\Exception\S3Exception. All service specific exceptions thrown by the SDK extend from the Aws\Exception\AwsException class. This class contains useful information about the failure, including the request-id, error code, and error type.

use Aws\Exception\AwsException;
use Aws\S3\Exception\S3Exception;

try {
    $s3Client->createBucket(['Bucket' => 'my-bucket']);
} catch (S3Exception $e) {
    // Catch an S3 specific exception.
    echo $e->getMessage();
} catch (AwsException $e) {
    // This catches the more generic AwsException. You can grab information
    // from the exception using methods of the exception object.
    echo $e->getAwsRequestId() . "\n";
    echo $e->getAwsErrorType() . "\n";
    echo $e->getAwsErrorCode() . "\n";
}

Async Error Handling

Exceptions are not thrown when sending asynchronous requests. Instead, you must use the then() or otherwise() methods of the returned promise to receive the result or error.

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);

$promise->otherwise(function ($reason) {
    var_dump($reason);
});

// This does the same thing as the "otherwise" function.
$promise->then(null, function ($reason) {
    var_dump($reason);
});

You can "unwrap" the promise and cause the exception to be thrown instead.

use Aws\S3\Exception\S3Exception;

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);

try {
    $result = $promise->wait();
} catch (S3Exception $e) {
    echo $e->getMessage();
}