Using New Regions and Endpoints

Last week, a customer asked us how they could configure the AWS SDK for PHP to use Amazon SES with the EU (Ireland) Region. SES had just released support for the EU Region, but there was no tagged version of the SDK that supported it yet.

Our typical process is to push new support for regions to the master branch of the AWS SDK for PHP repository as soon as possible after they are announced. In fact, at the time that the customer asked us about EU Region support in SES, we had already pushed out support for it. However, if you are using only tagged versions of the SDK, which you should do with production code, then you may have to wait 1 or 2 weeks until a new version of the SDK is released.

Configuring the base URL of your client

Fortunately, there is a way to use new regions and endpoints, even if the SDK does not yet support a new region for a service. You can manually configure the base_url of a client when you instantiate it. For example, to configure an SES client to use the EU Region, do the following:

$ses = AwsSesSesClient::factory(array(
    'key'      => 'YOUR_AWS_ACCESS_KEY_ID',
    'secret'   => 'YOUR_AWS_SECRET_KEY',
    'region'   => 'eu-west-1',
    'base_url' => 'https://email.eu-west-1.amazonaws.com',
));

Remember, you only need to specify the base_url if the SDK doesn’t already support the region. For regions that the SDK does support, the endpoint is automatically determined.

To find the correct URL to use for your desired service and region, see the Regions and Endpoints page of the AWS General Reference documentation.

Using the base_url for other reasons

The base_url option can be used for more than just accessing new regions. It can be used to allow the SDK to send requests to any endpoint compatible with the API of the service you are using (e.g., mock/test services, private beta endpoints).

An example of this is the DynamoDB Local tool that acts as a small client-side database and server that mimics Amazon DynamoDB. You can easily configure a DynamoDB client to work with DynamoDB Local by using the base_url option (assuming you have correctly installed and started DynamoDB Local).

$dynamodb = AwsDynamoDbDynamoDbClient::factory(array(
    'key'      => 'YOUR_AWS_ACCESS_KEY_ID',
    'secret'   => 'YOUR_AWS_SECRET_KEY',
    'region'   => 'us-east-1',
    'base_url' => 'http://localhost:8000',
));

For more information, see Setting a custom endpoint in the AWS SDK for PHP User Guide.

Using the latest SDK via Composer

If you are using Composer with the SDK, then you have another option for picking up new features, like newly supported regions, without modifying your code. If you need to use a new feature or bugfix that is not yet in a tagged release, you can do so by adjusting the SDK dependency in your composer.json file to use our development alias 2.5.x-dev.

{
    "require": {
        "aws/aws-sdk-php": "2.5.x-dev"
    }
}

Using the development alias, instead of dev-master, is ideal, because if you have other dependencies that require the SDK, version constraints like "2.5.*" will still resolve correctly. Remember that relying on a non-tagged version of the SDK is not recommended for production code.