quick-start.rst

Getting Started Guide

This "Getting Started Guide" focuses on basic usage of the AWS SDK for PHP. After reading through this material, you should be familiar with the SDK and be able to start using the SDK in your application. This guide assumes that you have already downloaded and installed the SDK <installation> and retrieved your AWS access keys.

Including the SDK

No matter which technique you have used to to install the SDK, the SDK can be included into your project or script with just a single include (or 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	Include 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 use the Composer installation method. If you are using a different installation method, then you can refer to this section and substitute in the proper code.

Creating a client object

To use the SDK, you first you need to instantiate a client object for the service you are using. We'll use the Amazon Simple Storage Service (Amazon S3) client as an example. You can instantiate a client using two different techniques.

Factory method

The easiest way to get up and running quickly is to use the web service client's factory() method and provide your credential profile (via the profile option), which identifies the set of credentials you want to use from your ~/.aws/credentials file (see credential_profiles).

<?php

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

use Aws\S3\S3Client;

// Instantiate the S3 client using your credential profile
$s3Client = S3Client::factory(array(
    'profile' => 'my_profile',
));

You can also choose to forgo specifying credentials if you are relying on instance profile credentials, provided via AWS Identity and Access Management (AWS IAM) roles for EC2 instances, or environment credentials sourced from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. For more information about credentials, see credentials.

Note

Instance profile credentials and other temporary credentials generated by the AWS Security Token Service (AWS STS) are not supported by every service. Please check if the service you are using supports temporary credentials by reading AWS Services that Support AWS STS.

Depending on the service, you may also need to provide a region value to the factory() method. The region value is used by the SDK to determine the regional endpoint to use to communicate with the service. Amazon S3 does not require you to provide a region, but other services like Amazon Elastic Compute Cloud (Amazon EC2) do. You can specify a region and other configuration settings along with your credentials in the array argument that you provide.

$ec2Client = \Aws\Ec2\Ec2Client::factory(array(
    'profile' => 'my_profile',
    'region'  => 'us-east-1',
));

To know if the service client you are using requires a region and to find out which regions are supported by the client, please see the appropriate service-specific guide <supported-services>.

Service builder

Another way to instantiate a service client is using the Aws\Common\Aws object (a.k.a the service builder). The Aws object is essentially a service locator, and allows you to specify credentials and configuration settings such that they can be shared across all client instances. Also, every time you fetch a client object from the Aws object, it will be exactly the same instance.

use Aws\Common\Aws;

// Create a service locator using a configuration file
$aws = Aws::factory(array(
    'profile' => 'my_profile',
    'region'  => 'us-east-1',
));

// Get client instances from the service locator by name
$s3Client = $aws->get('s3');
$ec2Client = $aws->get('ec2');

// The service locator always returns the same instance
$anotherS3Client = $aws->get('s3');
assert('$s3Client === $anotherS3Client');

You can also declare your credentials and settings in a configuration file, and provide the path to that file (in either php or json format) when you instantiate the Aws object.

// Create a `Aws` object using a configuration file
$aws = Aws::factory('/path/to/config.php');

// Get the client from the service locator by namespace
$s3Client = $aws->get('s3');

A simple configuration file should look something like this:

<?php return array(
    'includes' => array('_aws'),
    'services' => array(
        'default_settings' => array(
            'params' => array(
                'key'    => 'YOUR_AWS_ACCESS_KEY_ID',
                'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY',
                // OR: 'profile' => 'my_profile',
                'region' => 'us-west-2'
            )
        )
    )
);

For more information about configuration files, please see configuration.

Performing service operations

To learn about performing operations in more detail, including using command objects, see feature-commands.

Working with modeled responses

To learn more about how to work with modeled responses, read the detailed guide to feature-models.

Detecting and handling errors

When you preform an operation, and it succeeds, it will return a modeled response. If there was an error with the request, 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 a server-side 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.

try {
    $s3Client->createBucket(array(
        'Bucket' => 'my-bucket'
    ));
} catch (\Aws\S3\Exception\S3Exception $e) {
    // The bucket couldn't be created
    echo $e->getMessage();
}

Exceptions thrown by the SDK like this all extend the ServiceResponseException class (see the API docs), which has some custom methods that might help you discover what went wrong.

Waiters

To learn more about how to use and configure waiters, please read the detailed guide to feature-waiters.

Iterators

To learn more about how to use and configure iterators, please read the detailed guide to feature-iterators.