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.
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',
));
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.
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
|
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
|
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
|
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),
When using the This parameter can also be passed in using an SDK v3 forwards compatible way using
the |
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. |
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'
));
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.
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
.