The AWS SDK for PHP utilizes service descriptions and dynamic magic __call() methods to execute API operations. You can find a full list of methods available for a web service client in the API documentation of the client.
This issue can occur when using an out of date CA bundle with cURL and SSL. You can get around this issue by updating the CA bundle on your server or downloading a more up to date CA bundle from the cURL website directly.
The SDK will by default use the CA bundle that is configured when PHP is
compiled. You can change the default CA bundle used by PHP by modifying the
openssl.cafile
PHP ini configuration setting to be set to the path a CA
file on disk.
A version
option is required when creating a client. A list of available
API versions can be found on each client's API documentation page:
http://docs.aws.amazon.com/aws-sdk-php/v3/api/index.html. If you are unable to
load a specific API version, then you may need to update your copy of the SDK.
You may provide the string latest
to the "version" configuration value to
utilize the most recent available API version that your client's API provider
can find (the default api_provider will scan the src/data
directory of the
SDK for API models).
Warning
Using latest
in a production application is not recommended because
pulling in a new minor version of the SDK that includes an API update could
break your production application.
A region
option is required when creating a client, and is specified using
a string value. A list of available regions an endpoints can be found at:
http://docs.aws.amazon.com/general/latest/gr/rande.html
// Set the region to the EU (Frankfurt) region.
$s3 = new Aws\S3\S3Client([
'region' => 'eu-central-1',
'version' => '2006-03-01'
]);
Because PHP's integer type is signed and many platforms use 32-bit integers, the AWS SDK for PHP does not correctly handle files larger than 2GB on a 32-bit stack (where "stack" includes CPU, OS, web server, and PHP binary). This is a well-known PHP issue. In the case of Microsoft® Windows®, only builds of PHP 7 support 64-bit integers.
The recommended solution is to use a 64-bit Linux stack, such as the 64-bit Amazon Linux AMI with the latest version of PHP installed.
For more information, please see: PHP filesize: Return values.
You can get debug information, including the data sent over the wire, using the
debug
option in a client constructor. When this option is set to true
all of the mutations of the command being executed, the request being sent, the
response being received, and the result be processed will be emitted to STDOUT.
This includes the data that is sent and received over the wire.
$s3Client = new Aws\S3\S3Client([
'region' => 'us-standard',
'version' => '2006-03-01',
'debug' => true
]);
You can add any arbitrary headers to a service operation by adding a custom
middleware to the Aws\HandlerList
of an Aws\CommandInterface
or
Aws\ClientInterface
. The following example shows how to add an
X-Foo-Baz
header to a specific Amazon S3 PutObject operation using the
Aws\Middleware::mapRequest
helper method.
See mapRequest for more information.
You can sign an arbitrary PSR-7 request using the SDK's SignatureV4 class.
See Signing Custom CloudSearchDomain Requests for a full example of how to do so.
You can modify a command before sending it by adding a custom
middleware to the Aws\HandlerList
of an Aws\CommandInterface
or
Aws\ClientInterface
. The following example shows how to add custom command
parameters to a command before it is sent, essentially adding default options.
This example uses the Aws\Middleware::mapCommand
helper method.
See mapCommand for more information.
If you are seeing a Aws\Exception\CredentialsException
while while using
the SDK, then this means that the SDK was not provided with any credentials and
was unable to find credentials in the environment.
If you instantiate a client without credentials, on the first time that you
perform a service operation, the SDK will attempt to find credentials. It first
checks in some specific environment variables, then it looks for instance
profile credentials, which are only available on configured Amazon EC2
instances. If absolutely no credentials are provided or found, an
Aws\Exception\CredentialsException
is thrown.
If you are seeing this error and you are intending to use instance profile credentials, then you need to make sure that the Amazon EC2 instance that the SDK is running on is configured with an appropriate IAM role.
If you are seeing this error and you are not intending to use instance profile credentials, then you need to make sure that you are properly providing credentials to the SDK.
For more information, see Credentials.
The SDK does not currently run on HHVM, and won't be able to until the issue with the yield semantics in HHVM is resolved.
You can disable SSL by setting the scheme
parameter in a client factory
method to 'http'. It is important to note that not all services support
http
access. Please see regions and endpoints
for a list of regions, endpoints, and the supported schemes.
$client = new Aws\DynamoDb\DynamoDbClient([
'version' => '2012-08-10',
'region' => 'us-west-2',
'scheme' => 'http'
]);
Warning
Because SSL requires all data to be encrypted and requires more TCP packets to complete a connection handshake than just TCP, disabling SSL may provide a small performance improvement. However, with SSL disabled, all data is sent over the wire unencrypted. Before disabling SSL, you must carefully consider the security implications and the potential for eavesdropping over the network.
The PHP engine will throw parsing errors when it encounters syntax it does not understand. This is almost always encountered when attempting to run code that was written for a different version of PHP.
If you encounter a parsing error, please check your system and make sure it fulfills the SDK's Requirements.
Some HTTP handlers -- including the default Guzzle 6 HTTP handler -- will
inflate compressed response bodies by default. This behavior can be overridden
by setting the decode_content HTTP option to false
. For
backwards compatibility reasons, this default cannot be changed, but it is
recommended that you disable content decoding at the S3 client level.
See decode_content for an example of how to disable automatic content decoding.
You can disable body signing by setting the ContentSHA256
parameter in
command object to Aws\Signature\S3SignatureV4::UNSIGNED_PAYLOAD
. Then PHP SDK will use it as
the 'x-amz-content-sha-256' header and the body checksum in the canonical request.
$s3Client = new Aws\S3\S3Client([
'version' => '2006-03-01',
'region' => 'us-standard'
]);
$params = [
'Bucket' => 'foo',
'Key' => 'baz',
'ContentSHA256' => Aws\Signature\S3SignatureV4::UNSIGNED_PAYLOAD
];
// Using operation methods creates command implicitly.
$result = $s3Client->putObject($params);
// Using commands explicitly.
$command = $s3Client->getCommand('PutObject', $params);
$result = $s3Client->execute($command);
PHP SDK has a RetryMiddleware
that handles retry behavior. In terms of 5xx HTTP
status codes for server errors, SDK retries on 500, 502, 503 and 504.
Throttling exceptions including RequestLimitExceeded
, Throttling
,
ProvisionedThroughputExceededException
, ThrottlingException
, RequestThrottled
and BandwidthLimitExceeded
are handled with retries as well.
SDK also integrates exponential delay with backoff and jitter algorithm in retry scheme. Furthermore,
default retry behavior is configured as 3
for all services except dynamoDB, which is 10
.
Besides SDK customized Exception classes, each Aws Service Client has its own exception class that
inherits from AwsExceptionAwsException.
You can determine more specific error types to catch with the API specific errors listed under the
Errors
section of each method.
Error Code information is available with getAwsErrorCode()
from Aws\Exception\AwsException
.
$sns = new \Aws\Sns\SnsClient([
'region' => 'us-west-2',
'version' => 'latest',
]);
try {
$sns->publish([
// parameters
...
]);
// do something
} catch (SnsException $e) {
switch ($e->getAwsErrorCode()) {
case 'EndpointDisabled':
case 'NotFound':
// do something
break;
}
}