PHP: Adds metadata file and support for creating the Express subdirec…

…tory in S3 for PHP, and moves those files. (#7094) * Adds metadata file and support for creating the Express subdirectory in S3 for PHP, and moves those files. Co-authored-by: Laren-AWS <[email protected]> --------- Co-authored-by: Laren-AWS <[email protected]>
awsdocs · Nov 21, 2024 · 3cc3453 · 3cc3453
1 parent 529c7f0
commit 3cc3453
Show file tree

Hide file tree

Showing 9 changed files with 135 additions and 59 deletions.
diff --git a/.doc_gen/cross-content/phrases-code-examples.ent b/.doc_gen/cross-content/phrases-code-examples.ent
@@ -162,3 +162,6 @@
 <!ENTITY CFJS10 'JavaScript runtime 1.0 for &CF; Functions'>
 <!ENTITY CFJS20long 'JavaScript runtime 2.0 for &CFlong; Functions'>
 <!ENTITY CFJS20 'JavaScript runtime 2.0 for &CF; Functions'>
+
+<!-- S3 only entity to account for super-short usage -->
+<!ENTITY S3only 'S3'>
diff --git a/.doc_gen/metadata/s3-directory-buckets_metadata.yaml 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/express
+          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
@@ -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
@@ -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
@@ -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:
 <!--custom.basics.s3_Scenario_GettingStarted.start-->
 <!--custom.basics.s3_Scenario_GettingStarted.end-->
 
-#### 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
-
-<!--custom.basic_prereqs.s3_Scenario_ExpressBasics.start-->
-<!--custom.basic_prereqs.s3_Scenario_ExpressBasics.end-->
-
-
-<!--custom.basics.s3_Scenario_ExpressBasics.start-->
-<!--custom.basics.s3_Scenario_ExpressBasics.end-->
-
 
 #### Create a presigned URL
 

diff --git a/php/example_code/s3/ExpressRunner.php → ...example_code/s3/express/ExpressRunner.php b/php/example_code/s3/ExpressRunner.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
@@ -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.
+
+<!--custom.overview.start-->
+<!--custom.overview.end-->
+
+_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).
+
+<!--custom.important.start-->
+<!--custom.important.end-->
+
+## Code examples
+
+### Prerequisites
+
+For prerequisites, see the [README](../../../README.md#Prerequisites) in the `php` folder.
+
+
+<!--custom.prerequisites.start-->
+<!--custom.prerequisites.end-->
+
+### Basics
+
+Code examples that show you how to perform the essential operations within a service.
+
+- [Learn the basics](S3ExpressBasics.php)
+
+
+<!--custom.examples.start-->
+<!--custom.examples.end-->
+
+## Run the examples
+
+### Instructions
+
+
+<!--custom.instructions.start-->
+<!--custom.instructions.end-->
+
+
+#### 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
+
+<!--custom.basic_prereqs.s3-directory-buckets_Scenario_ExpressBasics.start-->
+<!--custom.basic_prereqs.s3-directory-buckets_Scenario_ExpressBasics.end-->
+
+
+<!--custom.basics.s3-directory-buckets_Scenario_ExpressBasics.start-->
+<!--custom.basics.s3-directory-buckets_Scenario_ExpressBasics.end-->
+
+
+### 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.
+
+
+
+<!--custom.tests.start-->
+<!--custom.tests.end-->
+
+## 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)
+
+<!--custom.resources.start-->
+<!--custom.resources.end-->
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
diff --git a/php/example_code/s3/S3ExpressBasics.php → ...ample_code/s3/express/S3ExpressBasics.php b/php/example_code/s3/S3ExpressBasics.php → ...ample_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/...ple_code/s3/tests/S3ExpressBasicsTest.php → .../s3/express/tests/S3ExpressBasicsTest.php b/...ple_code/s3/tests/S3ExpressBasicsTest.php → .../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