From a85677b2c4ee228f407b0db48301f77a0c3f8b40 Mon Sep 17 00:00:00 2001 From: Jeremy Lindblom Date: Thu, 19 Jun 2014 15:23:27 -0700 Subject: [PATCH] Updated various parts of the user guide. --- README.md | 25 +++++++-------- docs/installation.rst | 10 +++++- docs/migration-guide.rst | 10 ++---- docs/quick-start.rst | 2 -- docs/service-autoscaling.rst | 2 -- docs/service-cloudformation.rst | 2 -- docs/service-cloudfront-20120505.rst | 2 -- docs/service-cloudfront.rst | 2 -- docs/service-cloudsearch.rst | 2 -- docs/service-cloudtrail.rst | 2 -- docs/service-cloudwatch.rst | 2 -- docs/service-datapipeline.rst | 2 -- docs/service-directconnect.rst | 2 -- docs/service-ec2.rst | 2 -- docs/service-elasticache.rst | 2 -- docs/service-elasticbeanstalk.rst | 2 -- docs/service-elasticloadbalancing.rst | 2 -- docs/service-elastictranscoder.rst | 2 -- docs/service-emr.rst | 2 -- docs/service-glacier.rst | 2 -- docs/service-iam.rst | 2 -- docs/service-importexport.rst | 2 -- docs/service-kinesis.rst | 2 -- docs/service-opsworks.rst | 2 -- docs/service-rds.rst | 2 -- docs/service-route53.rst | 2 -- docs/service-s3.rst | 31 +++---------------- docs/service-ses.rst | 2 -- docs/service-sns.rst | 2 -- docs/service-sqs.rst | 12 ++----- docs/service-storagegateway.rst | 2 -- docs/service-sts.rst | 2 -- docs/service-support.rst | 2 -- docs/service-swf.rst | 2 -- .../Tests/S3/Integration/S3_20060301_Test.php | 2 +- 35 files changed, 32 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index 7214b9253b..7a202c5c53 100644 --- 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 index ee573002c3..99d79bcf92 100644 --- 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 `_ 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 `_ 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 index d20191f235..28bdad21a0 100644 --- 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 index 2c84b9380e..c3326427ad 100644 --- 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 index ceed81433b..5bf1ffdc0b 100644 --- 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 index bc932f1cfd..4abbae27dc 100644 --- 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 index 1feb701b8e..b15f320797 100644 --- 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 -.. include:: _snippets/incomplete.txt - .. apiref:: CloudFront 2012-05-05 diff --git a/docs/service-cloudfront.rst b/docs/service-cloudfront.rst index 4190b265ec..fba073334d 100644 --- 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 -.. include:: _snippets/incomplete.txt - .. apiref:: CloudFront diff --git a/docs/service-cloudsearch.rst b/docs/service-cloudsearch.rst index a7a3af2e36..aa2f87062e 100644 --- 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 index e8112c60d3..97526f6c16 100644 --- a/docs/service-cloudtrail.rst +++ b/docs/service-cloudtrail.rst @@ -6,6 +6,4 @@ Blog articles * `Using AWS CloudTrail in PHP - Part 1 `_ * `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 index fca0b50111..aa4ef67664 100644 --- 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 index 8006580b93..e815620dfb 100644 --- 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 index cfe646a322..f8e8d3211b 100644 --- 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 index 7807fbc558..a25fca6967 100644 --- 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 index 3b273efae6..af72ea9492 100644 --- 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 index f05463d5a6..4eb9019550 100644 --- 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 index 01348d54ce..14cc13d00d 100644 --- 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 index e74d682a76..83d00dee1c 100644 --- 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 index 70e74b1c1b..8c00443002 100644 --- 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 index 7d407fcdbd..eeae2956e5 100644 --- 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 index 82619bb35d..9db202f36a 100644 --- 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 index 6cf780ebf4..5dd7bb824b 100644 --- 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 index 1fcd3c701f..09931c5a2b 100644 --- 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 index 5eefaa4e63..f3358b056a 100644 --- 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 index c9541abcb7..37b9c369ba 100644 --- 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 index b6d8a5c9ce..59df69e916 100644 --- 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 index cbcb6e4c42..a91bf78eea 100644 --- 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,19 +198,6 @@ 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 @@ -227,15 +205,14 @@ 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 index f38b85eb54..29646461fe 100644 --- 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 index 097fe03f44..fd7e96f584 100644 --- 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 index d77dc21980..30c2567c69 100644 --- 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 index 45fa360938..8556e41973 100644 --- 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 index ef66635d1e..bd8c41f431 100644 --- 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 index 217073a0f2..d49020c050 100644 --- 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 index 9c60ee9acc..f96396a1b3 100644 --- a/docs/service-swf.rst +++ b/docs/service-swf.rst @@ -1,5 +1,3 @@ .. service:: Swf -.. include:: _snippets/incomplete.txt - .. apiref:: Swf diff --git a/tests/Aws/Tests/S3/Integration/S3_20060301_Test.php b/tests/Aws/Tests/S3/Integration/S3_20060301_Test.php index 805224cad2..c565e7c8d8 100644 --- a/tests/Aws/Tests/S3/Integration/S3_20060301_Test.php +++ b/tests/Aws/Tests/S3/Integration/S3_20060301_Test.php @@ -98,7 +98,7 @@ public function testCreateBucketInRegion() // Create a valid bucket and use a LocationConstraint $result = $client->createBucket(array( 'Bucket' => $bucket, - 'LocationConstraint' => \Aws\Common\Enum\Region::US_WEST_2 + 'LocationConstraint' => 'us-west-2', )); // Get the Location header of the response