Updated various parts of the user guide.

jeremeamia · Jun 19, 2014 · a85677b · a85677b
1 parent 38fe71b
commit a85677b
Show file tree

Hide file tree

Showing 35 changed files with 32 additions and 116 deletions.
diff --git a/README.md b/README.md
@@ -26,11 +26,11 @@ minutes by [installing the SDK through Composer][docs-installation] or by downlo
 
 * Provides easy-to-use HTTP clients for all supported AWS [services][docs-services], [regions][docs-rande], and
   authentication protocols.
-* Is built for PHP 5.3.3+ and is compliant with [PSR-0][], [PSR-1][], and [PSR-2][].
-* Is easy to install through [Composer][install-packagist], [PEAR][install-pear], or single download ([zip][install-zip]
-  or [phar][install-phar]).
-* Is built on [Guzzle v3][guzzle], and utilizes many of its features including persistent connections, parallel requests, 
-  events and plugins (via [Symfony2 EventDispatcher][symfony2-events]), service descriptions, [over-the-wire
+* Is built for PHP 5.3.3+ and is compliant with [PSR-0], [PSR-1], and [PSR-2].
+* Is easy to install through [Composer][install-packagist], or by downloading the [phar][install-phar] or
+  [zip][install-zip].
+* Is built on [Guzzle v3][guzzle], and utilizes many of its features, including persistent connections, parallel
+  requests, events and plugins (via [Symfony2 EventDispatcher][symfony2-events]), service descriptions, [over-the-wire
   logging][docs-wire-logging], caching, flexible batching, and request retrying with truncated exponential backoff.
 * Provides convenience features including easy response pagination via [Iterators][docs-iterators], resource
   [Waiters][docs-waiters], and simple [modelled responses][docs-models].
@@ -46,13 +46,12 @@ minutes by [installing the SDK through Composer][docs-installation] or by downlo
 
 1. **Sign up for AWS** – Before you begin, you need to [sign up for an AWS account][docs-signup] and retrieve your AWS
    credentials.
-1. **Minimum requirements** – To run the SDK, your system will need to meet the [minimum
-   requirements][docs-requirements], including having **PHP 5.3.3+** compiled with the cURL extension and cURL 7.16.2+
-   compiled with OpenSSL and zlib.
-1. **Install the SDK** – Using [Composer][] is the recommended way to install the AWS SDK for PHP. The SDK is available
-   via [Packagist][] under the [`aws/aws-sdk-php`][install-packagist] package. Please see the
-   [Installation section of the User Guide][docs-installation] for more detailed information about installing the SDK
-   through Composer and other means (e.g., [Phar][install-phar], [Zip][install-zip], [PEAR][install-pear]).
+1. **Minimum requirements** – To run the SDK, your system will need to meet the [minimum requirements][docs-requirements],
+   including having **PHP 5.3.3+** compiled with the cURL extension and cURL 7.16.2+ compiled with OpenSSL and zlib.
+1. **Install the SDK** – Using [Composer] is the recommended way to install the AWS SDK for PHP. The SDK is available
+   via [Packagist] under the [`aws/aws-sdk-php`][install-packagist] package. Please see the [Installation section of
+   the User Guide][docs-installation] for more detailed information about installing the SDK through Composer and other
+   means.
 1. **Using the SDK** – The best way to become familiar with how to use the SDK is to read the [User Guide][docs-guide].
    The [Getting Started Guide][docs-quickstart] will help you become familiar with the basic concepts, and there are
    also specific guides for each of the [supported services][docs-services].
@@ -105,7 +104,7 @@ try {
 * [Put an item in your Amazon DynamoDB table][example-dynamodb-putitem]
 * [Send a message to your Amazon SQS queue][example-sqs-sendmessage]
 * Please browse the [User Guide][docs-guide] and [API docs][docs-api] or check out our [AWS SDK Development
-  Blog][sdk-blog] for even more examples.
+  Blog][sdk-blog] for even more examples and tutorials.
 
 ### Related Projects
 

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -105,7 +105,7 @@ following required and suggested libraries:
 
 Using the zip file is great if you:
 
-1. Prefer not to or cannot use package managers like Composer and PEAR.
+1. Prefer not to or cannot use Composer.
 2. Cannot use phar files due to environment limitations.
 3. Want to use only specific files from the SDK.
 
@@ -122,6 +122,14 @@ If you have `phing <http://www.phing.info/>`_ installed, you can clone the SDK a
 Installing via PEAR
 ~~~~~~~~~~~~~~~~~~~
 
+.. admonition:: Installation via PEAR will soon be unsupported.
+
+    The use of PEAR as a dependency management system has declined in the PHP community in favor of Composer, and
+    notable projects like PHPUnit, Symfony, and Doctrine are all retiring their PEAR channels at various points
+    during this year. We will eventually stop updating our PEAR channel during this year, so we strongly recommend that
+    you switch to using Composer to install the AWS SDK for PHP.
+
+
 `PEAR <http://pear.php.net/>`_ packages are easy to install, and are available in your PHP environment path so that they
 are accessible to any PHP project. PEAR packages are not specific to your project, but rather to the machine they're
 installed on.

diff --git a/docs/migration-guide.rst b/docs/migration-guide.rst
@@ -41,9 +41,7 @@ What's New?
 - Plug-ins for over-the-wire logging and response caching
 - "Waiter" objects that allow you to poll a resource until it is in a desired state
 - Resource iterator objects for easily iterating over paginated responses
-- Service-specific sets of exceptions
 - Modeled responses with a simpler interface
-- Grouped constants (Enums) for service parameter options
 - Flexible request batching system
 - Service builder/container that supports easy configuration and dependency injection
 - Full unit test suite with extensive code coverage
@@ -450,8 +448,6 @@ From Version 2 of the SDK
     require '/path/to/vendor/autoload.php';
 
     use Aws\Common\Aws;
-    use Aws\DynamoDb\Enum\ComparisonOperator;
-    use Aws\DynamoDb\Enum\Type;
 
     $aws = Aws::factory('/path/to/config.php');
     $dynamodb = $aws->get('dynamodb');
@@ -462,9 +458,9 @@ From Version 2 of the SDK
         'AttributesToGet' => array('id', 'age', 'name'),
         'ScanFilter'      => array(
             'age' => array(
-                'ComparisonOperator' => ComparisonOperator::GE,
+                'ComparisonOperator' => 'GE',
                 'AttributeValueList' => array(
-                    array(Type::NUMBER => '16')
+                    array('N' => '16')
                 )
             ),
         )
@@ -474,7 +470,7 @@ From Version 2 of the SDK
     // that are 16 or older
     $people = array();
     foreach ($scan as $item) {
-        $people[] = $item['name'][Type::STRING];
+        $people[] = $item['name']['N'];
     }
 
     print_r($people);
diff --git a/docs/quick-start.rst b/docs/quick-start.rst
@@ -22,8 +22,6 @@ 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';``
--------------------------- ---------------------------------------------------------------------------------------------
-Using PEAR                 ``require 'AWSSDKforPHP/aws.phar';``
 ========================== =============================================================================================
 
 For the remainder of this guide, we will show examples that use the Composer installation method. If you are using a

diff --git a/docs/service-autoscaling.rst b/docs/service-autoscaling.rst
@@ -1,5 +1,3 @@
 .. service:: AutoScaling
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: AutoScaling
diff --git a/docs/service-cloudformation.rst b/docs/service-cloudformation.rst
@@ -1,5 +1,3 @@
 .. service:: CloudFormation
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: CloudFormation
diff --git a/docs/service-cloudfront-20120505.rst b/docs/service-cloudfront-20120505.rst
@@ -129,6 +129,4 @@ The following is an example of how you could use the signed URL to construct a w
     </body>
     </html>
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: CloudFront 2012-05-05
diff --git a/docs/service-cloudfront.rst b/docs/service-cloudfront.rst
@@ -129,6 +129,4 @@ The following is an example of how you could use the signed URL to construct a w
     </body>
     </html>
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: CloudFront
diff --git a/docs/service-cloudsearch.rst b/docs/service-cloudsearch.rst
@@ -1,5 +1,3 @@
 .. service:: CloudSearch
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: CloudSearch
diff --git a/docs/service-cloudtrail.rst b/docs/service-cloudtrail.rst
@@ -6,6 +6,4 @@ Blog articles
 * `Using AWS CloudTrail in PHP - Part 1 <http://blogs.aws.amazon.com/php/post/Tx3HGFCVGT92TS8/Using-AWS-CloudTrail-in-PHP-Part-1>`_
 * `Using AWS CloudTrail in PHP - Part 2 <http://blogs.aws.amazon.com/php/post/Tx31JYLN2SC3GHB/Using-AWS-CloudTrail-in-PHP-Part-2>`_
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: CloudTrail
diff --git a/docs/service-cloudwatch.rst b/docs/service-cloudwatch.rst
@@ -1,5 +1,3 @@
 .. service:: CloudWatch
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: CloudWatch
diff --git a/docs/service-datapipeline.rst b/docs/service-datapipeline.rst
@@ -1,5 +1,3 @@
 .. service:: DataPipeline
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: DataPipeline
diff --git a/docs/service-directconnect.rst b/docs/service-directconnect.rst
@@ -1,5 +1,3 @@
 .. service:: DirectConnect
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: DirectConnect
diff --git a/docs/service-ec2.rst b/docs/service-ec2.rst
@@ -1,5 +1,3 @@
 .. service:: Ec2
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Ec2
diff --git a/docs/service-elasticache.rst b/docs/service-elasticache.rst
@@ -1,5 +1,3 @@
 .. service:: ElastiCache
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: ElastiCache
diff --git a/docs/service-elasticbeanstalk.rst b/docs/service-elasticbeanstalk.rst
@@ -1,5 +1,3 @@
 .. service:: ElasticBeanstalk
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: ElasticBeanstalk
diff --git a/docs/service-elasticloadbalancing.rst b/docs/service-elasticloadbalancing.rst
@@ -1,5 +1,3 @@
 .. service:: ElasticLoadBalancing
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: ElasticLoadBalancing
diff --git a/docs/service-elastictranscoder.rst b/docs/service-elastictranscoder.rst
@@ -1,5 +1,3 @@
 .. service:: ElasticTranscoder
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: ElasticTranscoder
diff --git a/docs/service-emr.rst b/docs/service-emr.rst
@@ -1,5 +1,3 @@
 .. service:: Emr
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Emr
diff --git a/docs/service-glacier.rst b/docs/service-glacier.rst
@@ -1,5 +1,3 @@
 .. service:: Glacier
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Glacier
diff --git a/docs/service-iam.rst b/docs/service-iam.rst
@@ -1,5 +1,3 @@
 .. service:: Iam
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Iam
diff --git a/docs/service-importexport.rst b/docs/service-importexport.rst
@@ -1,5 +1,3 @@
 .. service:: ImportExport
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: ImportExport
diff --git a/docs/service-kinesis.rst b/docs/service-kinesis.rst
@@ -10,6 +10,4 @@ count.
 
 .. example:: Kinesis/Integration/Kinesis_20131104_Test.php testCreateStream
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Kinesis
diff --git a/docs/service-opsworks.rst b/docs/service-opsworks.rst
@@ -1,5 +1,3 @@
 .. service:: OpsWorks
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: OpsWorks
diff --git a/docs/service-rds.rst b/docs/service-rds.rst
@@ -1,5 +1,3 @@
 .. service:: Rds
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Rds
diff --git a/docs/service-route53.rst b/docs/service-route53.rst
@@ -1,5 +1,3 @@
 .. service:: Route53
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Route53
diff --git a/docs/service-s3.rst b/docs/service-s3.rst
@@ -22,19 +22,11 @@ bucket used in the examples of this tutorial in order for them to work correctly
 Creating a bucket in another region
 -----------------------------------
 
-The above example creates a bucket in the standard US-EAST-1 region. You can change the bucket location by passing a
+The above example creates a bucket in the standard us-east-1 region. You can change the bucket location by passing a
 ``LocationConstraint`` value.
 
 .. example:: S3/Integration/S3_20060301_Test.php testCreateBucketInRegion
 
-You'll notice in the above example that we are using the ``Aws\Common\Enum\Region`` object to provide the ``US_WEST_2``
-constant. The SDK provides various Enum classes under the ``Aws\Common\Enum`` namespace that can be useful for
-remembering available values and ensuring you do not enter a typo.
-
-.. note::
-
-    Using the enum classes is not required. You could just pass 'us-west-2' in the ``LocationConstraint`` key.
-
 Waiting until the bucket exists
 -------------------------------
 
@@ -150,7 +142,6 @@ easier to upload large files using multipart upload.
 
 .. code-block:: php
 
-    use Aws\Common\Enum\Size;
     use Aws\Common\Exception\MultipartUploadException;
     use Aws\S3\Model\MultipartUpload\UploadBuilder;
 
@@ -207,35 +198,21 @@ You can specify a canned ACL on an object when uploading:
         'ACL'        => 'public-read'
     ));
 
-You can use the ``Aws\S3\Enum\CannedAcl`` object to provide canned ACL constants:
-
-.. code-block:: php
-
-    use Aws\S3\Enum\CannedAcl;
-
-    $client->putObject(array(
-        'Bucket'     => 'mybucket',
-        'Key'        => 'data.txt',
-        'SourceFile' => '/path/to/data.txt',
-        'ACL'        => CannedAcl::PUBLIC_READ
-    ));
-
 You can specify more complex ACLs using the ``ACP`` parameter when sending PutObject, CopyObject, CreateBucket,
 CreateMultipartUpload, PutBucketAcl, PutObjectAcl, and other operations that accept a canned ACL. Using the ``ACP``
 parameter allows you specify more granular access control policies using a ``Aws\S3\Model\Acp`` object. The easiest
 way to create an Acp object is through the ``Aws\S3\Model\AcpBuilder``.
 
 .. code-block:: php
 
-    use Aws\S3\Enum\Permission;
     use Aws\S3\Enum\Group;
     use Aws\S3\Model\AcpBuilder;
 
     $acp = AcpBuilder::newInstance()
         ->setOwner($myOwnerId)
-        ->addGrantForEmail(Permission::READ, 'test@example.com')
-        ->addGrantForUser(Permission::FULL_CONTROL, 'user-id')
-        ->addGrantForGroup(Permission::READ, Group::AUTHENTICATED_USERS)
+        ->addGrantForEmail('READ', 'test@example.com')
+        ->addGrantForUser('FULL_CONTROL', 'user-id')
+        ->addGrantForGroup('READ', Group::AUTHENTICATED_USERS)
         ->build();
 
     $client->putObject(array(

diff --git a/docs/service-ses.rst b/docs/service-ses.rst
@@ -1,5 +1,3 @@
 .. service:: Ses
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Ses
diff --git a/docs/service-sns.rst b/docs/service-sns.rst
@@ -1,5 +1,3 @@
 .. service:: Sns
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Sns
diff --git a/docs/service-sqs.rst b/docs/service-sqs.rst
@@ -16,14 +16,11 @@ You can also set attributes on your queue when you create it.
 
 .. code-block:: php
 
-    use Aws\Common\Enum\Size;
-    use Aws\Sqs\Enum\QueueAttribute;
-
     $result = $client->createQueue(array(
         'QueueName'  => 'my-queue',
         'Attributes' => array(
-            QueueAttribute::DELAY_SECONDS        => 5,
-            QueueAttribute::MAXIMUM_MESSAGE_SIZE => 4 * Size::KB,
+            'DelaySeconds'       => 5,
+            'MaximumMessageSize' => 4096, // 4 KB
         ),
     ));
     $queueUrl = $result->get('QueueUrl');
@@ -32,13 +29,10 @@ Or you can also set queue attributes later.
 
 .. code-block:: php
 
-    use Aws\Common\Enum\Time;
-    use Aws\Sqs\Enum\QueueAttribute;
-
     $result = $client->setQueueAttributes(array(
         'QueueUrl'   => $queueUrl,
         'Attributes' => array(
-            QueueAttribute::VISIBILITY_TIMEOUT => 2 * Time::MINUTES,
+            'VisibilityTimeout' => 2 * 60 * 60, // 2 min
         ),
     ));
 

diff --git a/docs/service-storagegateway.rst b/docs/service-storagegateway.rst
@@ -1,5 +1,3 @@
 .. service:: StorageGateway
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: StorageGateway
diff --git a/docs/service-sts.rst b/docs/service-sts.rst
@@ -87,6 +87,4 @@ You can also use the same technique when setting credentials on an existing clie
     $credentials = $sts->createCredentials($sts->getSessionToken());
     $s3->setCredentials($credentials);
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Sts
diff --git a/docs/service-support.rst b/docs/service-support.rst
@@ -1,5 +1,3 @@
 .. service:: Support
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Support
diff --git a/docs/service-swf.rst b/docs/service-swf.rst
@@ -1,5 +1,3 @@
 .. service:: Swf
 
-.. include:: _snippets/incomplete.txt
-
 .. apiref:: Swf