From 01c6a367657fe7aeeef2389403a59864c74a400f Mon Sep 17 00:00:00 2001 From: Jason Quesenberry Date: Wed, 20 Nov 2024 16:24:50 -0700 Subject: [PATCH] Adds metadata file and support for creating the Express subdirectory in S3 for PHP, and moves those files. --- .../cross-content/phrases-code-examples.ent | 3 + .../s3-directory-buckets_metadata.yaml | 24 +++++ .doc_gen/metadata/s3_metadata.yaml | 26 ----- .tools/readmes/config.py | 3 + php/example_code/s3/README.md | 21 ---- .../s3/{ => express}/ExpressRunner.php | 1 + php/example_code/s3/express/README.md | 98 +++++++++++++++++++ .../s3/{ => express}/S3ExpressBasics.php | 9 +- .../tests/S3ExpressBasicsTest.php | 9 +- 9 files changed, 135 insertions(+), 59 deletions(-) create mode 100644 .doc_gen/metadata/s3-directory-buckets_metadata.yaml rename php/example_code/s3/{ => express}/ExpressRunner.php (94%) create mode 100644 php/example_code/s3/express/README.md rename php/example_code/s3/{ => express}/S3ExpressBasics.php (97%) rename php/example_code/s3/{ => express}/tests/S3ExpressBasicsTest.php (88%) diff --git a/.doc_gen/cross-content/phrases-code-examples.ent b/.doc_gen/cross-content/phrases-code-examples.ent index 036023db820..22179345b00 100644 --- a/.doc_gen/cross-content/phrases-code-examples.ent +++ b/.doc_gen/cross-content/phrases-code-examples.ent @@ -162,3 +162,6 @@ + + + diff --git a/.doc_gen/metadata/s3-directory-buckets_metadata.yaml b/.doc_gen/metadata/s3-directory-buckets_metadata.yaml new file mode 100644 index 00000000000..e25ddc38fb3 --- /dev/null +++ b/.doc_gen/metadata/s3-directory-buckets_metadata.yaml @@ -0,0 +1,24 @@ +s3-directory-buckets_Scenario_ExpressBasics: + synopsis_list: + - Set up a VPC and VPC Endpoint + - Set up the S3 Express Policies, Roles, and User to work with S3 Express buckets + - Create two S3 Clients + - Create two buckets + - Create an object and copy it over + - Demonstrate performance difference + - Populate the buckets to show the lexicographical difference + - Prompt the user to see if they want to clean up the resources + category: Basics + languages: + PHP: + versions: + - sdk_version: 3 + github: php/example_code/s3 + sdkguide: + excerpts: + - description: Run a scenario demonstrating the basics of &S3; Express One Zone. + snippet_tags: + - php.example_code.s3.ExpressBasics + - php.example_code.s3.service.S3Service + services: + s3-directory-buckets: {CreateBucket, CopyObject, GetObject, PutObject, ListObjects, DeleteObject, DeleteBucket} diff --git a/.doc_gen/metadata/s3_metadata.yaml b/.doc_gen/metadata/s3_metadata.yaml index 820cbc490a0..f8f183fc82b 100644 --- a/.doc_gen/metadata/s3_metadata.yaml +++ b/.doc_gen/metadata/s3_metadata.yaml @@ -3481,32 +3481,6 @@ s3_Scenario_ConditionalRequests: - python.example_code.s3.S3ConditionalRequests.wrapper services: s3: {GetObject, PutObject, CopyObject} -s3_Scenario_ExpressBasics: - title: Learn the basics of Amazon S3 Express One Zone with an &AWS; SDK - title_abbrev: Learn the basics of S3 Express One Zone - synopsis_list: - - Set up a VPC and VPC Endpoint - - Set up the S3 Express Policies, Roles, and User to work with S3 Express buckets - - Create two S3 Clients - - Create two buckets - - Create an object and copy it over - - Demonstrate performance difference - - Populate the buckets to show the lexicographical difference - - Prompt the user to see if they want to clean up the resources - category: Basics - languages: - PHP: - versions: - - sdk_version: 3 - github: php/example_code/s3 - sdkguide: - excerpts: - - description: - snippet_tags: - - php.example_code.s3.ExpressBasics - - php.example_code.s3.service.S3Service - services: - s3: {CreateVpc, DescribeRouteTables, CreateVpcEndpoint, CreateBucket, CopyObject, GetObject, PutObject, ListObjects, DeleteObject, DeleteBucket, DeleteVpcEndpoint, DeleteVpc} s3_Scenario_DownloadS3Directory: title: Download S3 'directories' from an &S3long; (&S3;) bucket title_abbrev: Download S3 'directories' diff --git a/.tools/readmes/config.py b/.tools/readmes/config.py index 0420b7da49a..4dc4d041bae 100644 --- a/.tools/readmes/config.py +++ b/.tools/readmes/config.py @@ -124,6 +124,9 @@ "base_folder": "php", "service_folder": 'php/example_code/{{service["name"]}}', "sdk_api_ref": 'https://docs.aws.amazon.com/aws-sdk-php/v3/api/namespace-Aws.{{service["name"] | capitalize}}.html', + "service_folder_overrides": { + "s3-directory-buckets": "php/example_code/s3/express", + } } }, "Python": { diff --git a/php/example_code/s3/README.md b/php/example_code/s3/README.md index f2ee898a7e9..ca812d8a862 100644 --- a/php/example_code/s3/README.md +++ b/php/example_code/s3/README.md @@ -39,7 +39,6 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `php` Code examples that show you how to perform the essential operations within a service. - [Learn the basics](GettingStartedWithS3.php) -- [Learn the basics of S3 Express One Zone](S3ExpressBasics.php) ### Single actions @@ -97,26 +96,6 @@ This example shows you how to do the following: -#### Learn the basics of S3 Express One Zone - -This example shows you how to do the following: - -- Set up a VPC and VPC Endpoint -- Set up the S3 Express Policies, Roles, and User to work with S3 Express buckets -- Create two S3 Clients -- Create two buckets -- Create an object and copy it over -- Demonstrate performance difference -- Populate the buckets to show the lexicographical difference -- Prompt the user to see if they want to clean up the resources - - - - - - - - #### Create a presigned URL diff --git a/php/example_code/s3/ExpressRunner.php b/php/example_code/s3/express/ExpressRunner.php similarity index 94% rename from php/example_code/s3/ExpressRunner.php rename to php/example_code/s3/express/ExpressRunner.php index 77d7094eb05..5926d3738d9 100644 --- a/php/example_code/s3/ExpressRunner.php +++ b/php/example_code/s3/express/ExpressRunner.php @@ -6,6 +6,7 @@ use Aws\Exception\AwsException; use AwsUtilities\RunnableExample; +use S3\express\S3ExpressBasics; require_once __DIR__ . "/vendor/autoload.php"; diff --git a/php/example_code/s3/express/README.md b/php/example_code/s3/express/README.md new file mode 100644 index 00000000000..f0461747743 --- /dev/null +++ b/php/example_code/s3/express/README.md @@ -0,0 +1,98 @@ +# S3 Directory Buckets code examples for the SDK for PHP + +## Overview + +Shows how to use the AWS SDK for PHP to work with Amazon S3 Directory Buckets. + + + + +_S3 Directory Buckets are designed to store data within a single AWS Zone. Directory buckets organize data hierarchically into directories, providing a structure similar to a file system._ + +## ⚠ Important + +* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/). +* Running the tests might result in charges to your AWS account. +* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). +* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services). + + + + +## Code examples + +### Prerequisites + +For prerequisites, see the [README](../../../README.md#Prerequisites) in the `php` folder. + + + + + +### Basics + +Code examples that show you how to perform the essential operations within a service. + +- [Learn the basics](S3ExpressBasics.php) + + + + + +## Run the examples + +### Instructions + + + + + + +#### Learn the basics + +This example shows you how to do the following: + +- Set up a VPC and VPC Endpoint +- Set up the S3 Express Policies, Roles, and User to work with S3 Express buckets +- Create two S3 Clients +- Create two buckets +- Create an object and copy it over +- Demonstrate performance difference +- Populate the buckets to show the lexicographical difference +- Prompt the user to see if they want to clean up the resources + + + + + + + + + +### Tests + +⚠ Running tests might result in charges to your AWS account. + + +To find instructions for running these tests, see the [README](../../../README.md#Tests) +in the `php` folder. + + + + + + +## Additional resources + +- [S3 Directory Buckets User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html) +- [S3 Directory Buckets API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) +- [SDK for PHP S3 Directory Buckets reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/namespace-Aws.S3-directory-buckets.html) + + + + +--- + +Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. + +SPDX-License-Identifier: Apache-2.0 \ No newline at end of file diff --git a/php/example_code/s3/S3ExpressBasics.php b/php/example_code/s3/express/S3ExpressBasics.php similarity index 97% rename from php/example_code/s3/S3ExpressBasics.php rename to php/example_code/s3/express/S3ExpressBasics.php index 4638bd819ca..a757518df71 100644 --- a/php/example_code/s3/S3ExpressBasics.php +++ b/php/example_code/s3/express/S3ExpressBasics.php @@ -20,7 +20,7 @@ * vendor/bin/phpunit S3ExpressBasicsTests.php **/ -namespace S3; +namespace S3\express; use Aws\CloudFormation\CloudFormationClient; use Aws\CloudFormation\Exception\CloudFormationException; use Aws\Credentials\Credentials; @@ -31,6 +31,7 @@ use AwsUtilities\RunnableExample; use Ec2\EC2Service; use Iam\IAMService; +use S3\S3Service; use function AwsUtilities\pressEnter; use function AwsUtilities\testable_readline; @@ -110,7 +111,7 @@ public function runExample() $this->cloudFormationClient = new CloudFormationClient([]); $stackName = "cfn-stack-s3-express-basics-" . uniqid(); - $file = file_get_contents(__DIR__ . "/../../../resources/cfn/s3_express_basics/s3_express_template.yml"); + $file = file_get_contents(__DIR__ . "/../../../../resources/cfn/s3_express_basics/s3_express_template.yml"); $result = $this->cloudFormationClient->createStack([ 'StackName' => $stackName, 'TemplateBody' => $file, @@ -138,14 +139,10 @@ public function runExample() $expressUserName = $output['OutputValue']; } } - $this->resources['regularUserName'] = $regularUserName; - $this->resources['expressUserName'] = $expressUserName; $regularKey = $this->iamService->createAccessKey($regularUserName); $regularCredentials = new Credentials($regularKey['AccessKeyId'], $regularKey['SecretAccessKey']); - $this->resources['regularKey'] = $regularKey['AccessKeyId']; $expressKey = $this->iamService->createAccessKey($expressUserName); $expressCredentials = new Credentials($expressKey['AccessKeyId'], $expressKey['SecretAccessKey']); - $this->resources['expressKey'] = $expressKey['AccessKeyId']; // 3. Create an additional client using the credentials with S3 Express permissions. echo "\n"; diff --git a/php/example_code/s3/tests/S3ExpressBasicsTest.php b/php/example_code/s3/express/tests/S3ExpressBasicsTest.php similarity index 88% rename from php/example_code/s3/tests/S3ExpressBasicsTest.php rename to php/example_code/s3/express/tests/S3ExpressBasicsTest.php index 4db50ee7842..7b0e9d14456 100644 --- a/php/example_code/s3/tests/S3ExpressBasicsTest.php +++ b/php/example_code/s3/express/tests/S3ExpressBasicsTest.php @@ -6,18 +6,15 @@ // Integration test runner for S3ExpressBasics.php. // -namespace S3\tests; +namespace S3\express\tests; -use Aws\CloudFormation\CloudFormationClient; use Aws\S3\Exception\S3Exception; -use Aws\S3\S3Client; use PHPUnit\Framework\TestCase; -use S3\S3ExpressBasics; -use S3\S3Service; +use S3\express\S3ExpressBasics; /** * @group integ - * @covers \S3\S3ExpressBasics + * @covers \S3\express\S3ExpressBasics * @covers \S3\S3Service */ class S3ExpressBasicsTest extends TestCase