Configuring the SDK

The AWS SDK for PHP can be configured in many ways to suit your needs. This guide highlights the use of configuration files with the service builder as well as individual client configuration options.

Configuration files

How configuration files work

When passing an array of parameters to the first argument of Aws\Common\Aws::factory(), the service builder loads the default aws-config.php file and merges the array of shared parameters into the default configuration.

Excerpt from src/Aws/Common/Resources/aws-config.php:

<?php return array(
    'class' => 'Aws\Common\Aws',
    'services' => array(
        'default_settings' => array(
            'params' => array()
        ),
        'autoscaling' => array(
            'alias'   => 'AutoScaling',
            'extends' => 'default_settings',
            'class'   => 'Aws\AutoScaling\AutoScalingClient'
        ),
        'cloudformation' => array(
            'alias'   => 'CloudFormation',
            'extends' => 'default_settings',
            'class'   => 'Aws\CloudFormation\CloudFormationClient'
        ),
    // ...
);

The aws-config.php file provides default configuration settings for associating client classes with service names. This file tells the Aws\Common\Aws service builder which class to instantiate when you reference a client by name.

You can supply your credential profile (see Using the AWS credentials file and credential profiles) and other configuration settings to the service builder so that each client is instantiated with those settings. To do this, pass an array of settings (including your profile) into the first argument of Aws\Common\Aws::factory().

<?php

require 'vendor/autoload.php';

use Aws\Common\Aws;

$aws = Aws::factory(array(
    'profile' => 'my_profile',
    'region'  => 'us-east-1',
));

Using a custom configuration file

You can use a custom configuration file that allows you to create custom named clients with pre-configured settings.

Let's say you want to use the default aws-config.php settings, but you want to supply your keys using a configuration file. Each service defined in the default configuration file extends from default_settings service. You can create a custom configuration file that extends the default configuration file and add credentials to the default_settings service:

<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'default_settings' => array(
            'params' => array(
                'profile' => 'my_profile', // Looks up credentials in ~/.aws/credentials
                'region'  => 'us-west-2'
            )
        )
    )
);

Make sure to include the 'includes' => array('_aws'), line in your configuration file, because this extends the default configuration that makes all of the service clients available to the service builder. If this is missing, then you will get an exception when trying to retrieve a service client.

You can use your custom configuration file with the Aws\Common\Aws class by passing the full path to the configuration file in the first argument of the factory() method:

<?php

require 'vendor/autoload.php';

use Aws\Common\Aws;

$aws = Aws::factory('/path/to/custom/config.php');

You can create custom named services if you need to, for example, use multiple accounts/credentials with the same service:

<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'foo.dynamodb' => array(
            'extends' => 'dynamodb',
            'params'  => array(
                'profile' => 'my_profile',
                'region'  => 'us-west-2'
            )
        ),
        'bar.dynamodb' => array(
            'extends' => 'dynamodb',
            'params'  => array(
                'profile' => 'my_other_profile',
                'region'  => 'us-west-2'
            )
        )
    )
);

If you prefer JSON syntax, you can define your configuration in JSON format instead of PHP.

{
    "includes": ["_aws"],
    "services": {
        "default_settings": {
            "params": {
                "profile": "my_profile",
                "region": "us-west-2"
            }
        }
    }
}

For more information about writing custom configuration files, please see Using the Service Builder in the Guzzle documentation.

Client configuration options

Basic client configuration options include your credentials profile (see Providing Credentials to the SDK) and a region (see Specifying a region). For typical use cases, you will not need to provide more than these 3 options. The following represents all of the possible client configuration options for service clients in the SDK.

Credentials Options
Options	Description
profile	The AWS credential profile associated with the credentials you want to use. The profile is used to look up your credentials in your credentials file (~/.aws/credentials). See Using the AWS credentials file and credential profiles for more information.
token.ttd	The UNIX timestamp for when the provided credentials expire.
credentials	An associative array containing the "key", "secret", and optional "token" key value pairs, or a credentials object (Aws\Common\Credentials\CredentialsInterface) can be provided instead explicit access keys and tokens.
key	An AWS access key ID. Unless you are setting temporary credentials provided by AWS STS, it is recommended that you avoid hard-coding credentials with this parameter. Please see Providing Credentials to the SDK for my information about credentials. Note key is deprecated, and is not supported in v3 of the AWS SDK for PHP. Please consider using the ``credentials``option.
secret	An AWS secret access key. Unless you are setting temporary credentials provided by AWS STS, it is recommended that you avoid hard-coding credentials with this parameter. Please see Providing Credentials to the SDK for my information about credentials. Note secret is deprecated, and is not supported in v3 of the AWS SDK for PHP. Please consider using the ``credentials``option.
token	An AWS security token to use with request authentication. These are typically provided by the AWS STS service. Please note that not all services accept temporary credentials. See http://docs.aws.amazon.com/STS/latest/UsingSTS/UsingTokens.html. Note token is deprecated, and is not supported in v3 of the AWS SDK for PHP . Please consider using the ``credentials``option.

Endpoint and Signature Options
Options	Description
region	Region name (e.g., 'us-east-1', 'us-west-1', 'us-west-2', 'eu-west-1', etc.). See Specifying a region.
scheme	URI Scheme of the base URL (e.g.. 'https', 'http') used when endpoint is not supplied.
endpoint	Allows you to specify a custom endpoint instead of have the SDK build one automatically from the region and scheme.
signature	Overrides the signature used by the client. Clients will always choose an appropriate default signature. However, it can be useful to override this with a custom setting. This can be set to "v4", "v3https", "v2" or an instance of Aws\Common\Signature\SignatureInterface.
signature.service	The signature service scope for Signature V4. See Setting a custom endpoint.
signature.region	The signature region scope for Signature V4. See Setting a custom endpoint.

Generic Client Options
Options	Description
ssl.certificate_authority	Set to true to use the SDK bundled SSL certificate bundle (this is used by default), 'system' to use the bundle on your system, a string pointing to a file to use a specific certificate file, a string pointing to a directory to use multiple certificates, or false to disable SSL validation (not recommended). When using the aws.phar, the bundled SSL certificate will be extracted to your system's temp folder, and each time a client is created an MD5 check will be performed to ensure the integrity of the certificate. This parameter can also be passed in using an SDK v3 forwards compatible way using the ['http']['verify'] key (e.g., $config['http']['verify'] = true).
curl.options	Associative array of cURL options to apply to every request created by the client. If either the key or value of an entry in the array is a string, Guzzle will attempt to find a matching defined cURL constant automatically (e.g. "CURLOPT_PROXY" will be converted to the constant CURLOPT_PROXY).
request.options	Associative array of Guzzle request options to apply to every request created by the client.
command.params	An associative array of default options to set on each command created by the client.
client.backoff.logger	A Guzzle\Log\LogAdapterInterface object used to log backoff retries. Use 'debug' to emit PHP warnings when a retry is issued.
client.backoff.logger.template	Optional template to use for exponential backoff log messages. See the Guzzle\Plugin\Backoff\BackoffLogger class for formatting information.

Specifying a region

Some clients require a region configuration setting. You can find out if the client you are using requires a region and the regions available to a client by consulting the documentation for that particular client (see Service-Specific Guides).

Here's an example of creating an Amazon DynamoDB client that uses the us-west-1 region:

require 'vendor/autoload.php';

use Aws\DynamoDb\DynamoDbClient;

// Create a client that uses the us-west-1 region
$client = DynamoDbClient::factory(array(
    'credentials' => array(
        'key'    => 'YOUR_AWS_ACCESS_KEY_ID',
        'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY',
    ),
    'region' => 'us-west-1'
));

Setting a custom endpoint

You can specify a completely customized endpoint for a client using the client's endpoint option. If the client you are using requires a region, then must still specify the name of the region using the region option. Setting a custom endpoint can be useful if you're using a mock web server that emulates a web service, you're testing against a private beta endpoint, or you are trying to a use a new region not yet supported by the SDK.

Here's an example of creating an Amazon DynamoDB client that uses a completely customized endpoint:

require 'vendor/autoload.php';

use Aws\DynamoDb\DynamoDbClient;

// Create a client that that contacts a completely customized base URL
$client = DynamoDbClient::factory(array(
    'endpoint' => 'http://my-custom-url',
    'region'   => 'my-region-1',
    'credentials' => array(
        'key'      => 'abc',
        'secret'   => '123'
    )
));

If your custom endpoint uses signature version 4 and must be signed with custom signature scoping values, then you can specify the signature scoping values using signature.service (the scoped name of the service) and signature.region (the region that you are contacting). These values are typically not required.

Using a proxy

You can send requests with the AWS SDK for PHP through a proxy using the "request options" of a client. These "request options" are applied to each HTTP request sent from the client. One of the option settings that can be specified is the proxy option.

Request options are passed to a client through the client's factory method:

use Aws\S3\S3Client;

$s3 = S3Client::factory(array(
    'request.options' => array(
        'proxy' => '127.0.0.1:123'
    )
));

The above example tells the client that all requests should be proxied through an HTTP proxy located at the 127.0.0.1 IP address using port 123.

You can supply a username and password when specifying your proxy setting if needed, using the format of username:password@host:port.