1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
=====================
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 :doc:`downloaded and installed the SDK <installation>` and retrieved your `AWS access keys
<http://aws.amazon.com/developers/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.
.. _client_factory_method:
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 :ref:`credential_profiles`).
.. code-block:: php
<?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 <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#UsingIAMrolesWithAmazonEC2Instances>`_,
or **environment credentials** sourced from the ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` environment
variables. For more information about credentials, see :doc:`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 <http://docs.aws.amazon.com/STS/latest/UsingSTS/UsingTokens.html>`_.
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 <http://docs.aws.amazon.com/general/latest/gr/rande.html>`_ 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.
.. code-block:: php
$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 :ref:`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 <http://en.wikipedia.org/wiki/Service_locator_pattern>`_, 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.
.. code-block:: php
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.
.. code-block:: php
// 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:
.. code-block:: php
<?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 :doc:`configuration`.
Performing service operations
-----------------------------
.. include:: _snippets/performing-operations.txt
To learn about performing operations in more detail, including using command objects, see :doc:`feature-commands`.
Working with modeled responses
------------------------------
.. include:: _snippets/models-intro.txt
To learn more about how to work with modeled responses, read the detailed guide to :doc:`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``.
.. code-block:: php
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
<http://docs.aws.amazon.com/aws-sdk-php/latest/class-Aws.Common.Exception.ServiceResponseException.html>`_), which has
some custom methods that might help you discover what went wrong.
Waiters
-------
.. include:: _snippets/waiters-intro.txt
To learn more about how to use and configure waiters, please read the detailed guide to :doc:`feature-waiters`.
Iterators
---------
.. include:: _snippets/iterators-intro.txt
To learn more about how to use and configure iterators, please read the detailed guide to :doc:`feature-iterators`.
|
