From 0d0bb1c574f9db8620634e31d0b7dacbc702bd53 Mon Sep 17 00:00:00 2001 From: Laurent VOULLEMIER Date: Mon, 14 Jan 2019 21:47:21 +0100 Subject: [PATCH] doc/radosgw: update doc with last S3 client The documentation for the S3 PHP client usage is about an old client. This update the examples to the current S3 PHP client. Signed-off-by: Laurent VOULLEMIER --- doc/radosgw/s3/php.rst | 144 +++++++++++++++++++++-------------------- 1 file changed, 75 insertions(+), 69 deletions(-) diff --git a/doc/radosgw/s3/php.rst b/doc/radosgw/s3/php.rst index c5079f5febaf..4878a34898ff 100644 --- a/doc/radosgw/s3/php.rst +++ b/doc/radosgw/s3/php.rst @@ -3,51 +3,65 @@ PHP S3 Examples =============== +Installing AWS PHP SDK +---------------------- + +This installs AWS PHP SDK using composer (see here_ how to install composer). + +.. _here: https://getcomposer.org/download/ + +.. code-block:: bash + + $ composer install aws/aws-sdk-php + Creating a Connection --------------------- This creates a connection so that you can interact with the server. +.. note:: + + The client initialization requires a region so we use ``''``. + .. code-block:: php AWS_KEY, - 'secret' => AWS_SECRET_KEY, - 'canonical_id' => AWS_CANONICAL_ID, - 'canonical_name' => AWS_CANONICAL_NAME, - )); - $Connection->set_hostname($HOST); - $Connection->allow_hostname_override(false); - - // Set the S3 class to use objects.dreamhost.com/bucket - // instead of bucket.objects.dreamhost.com - $Connection->enable_path_style(); - + $client = new S3Client([ + 'region' => '', + 'version' => '2006-03-01', + 'endpoint' => $ENDPOINT, + 'credentials' => [ + 'key' => AWS_KEY, + 'secret' => AWS_SECRET_KEY + ], + // Set the S3 class to use objects.dreamhost.com/bucket + // instead of bucket.objects.dreamhost.com + 'use_path_style_endpoint' => true + ]); Listing Owned Buckets --------------------- -This gets a list of CFSimpleXML objects representing buckets that you -own. This also prints out the bucket name and creation date of each -bucket. +This gets a ``AWS\Result`` instance that is more convenient to visit using array access way. +This also prints out the bucket name and creation date of each bucket. .. code-block:: php list_buckets(); - $Buckets = $ListResponse->body->Buckets->Bucket; - foreach ($Buckets as $Bucket) { - echo $Bucket->Name . "\t" . $Bucket->CreationDate . "\n"; + $listResponse = $client->listBuckets(); + $buckets = $listResponse['Buckets']; + foreach ($buckets as $bucket) { + echo $bucket['Name'] . "\t" . $bucket['CreationDate'] . "\n"; } The output will look something like this:: @@ -61,39 +75,33 @@ Creating a Bucket ----------------- This creates a new bucket called ``my-new-bucket`` and returns a -``CFResponse`` object. - -.. note:: - - This command requires a region as the second argument, - so we use ``AmazonS3::REGION_US_E1``, because this constant is ``''`` +``AWS\Result`` object. .. code-block:: php create_bucket('my-new-bucket', AmazonS3::REGION_US_E1); + $client->createBucket(['Bucket' => 'my-new-bucket']); List a Bucket's Content ----------------------- -This gets an array of ``CFSimpleXML`` objects representing the objects -in the bucket. This then prints out each object's name, the file size, -and last modified date. +This gets a ``AWS\Result`` instance that is more convenient to visit using array access way. +This then prints out each object's name, the file size, and last modified date. .. code-block:: php list_objects($bucketname); - $Objects = $ObjectsListResponse->body->Contents; - foreach ($Objects as $Object) { - echo $Object->Key . "\t" . $Object->Size . "\t" . $Object->LastModified . "\n"; + $objectsListResponse = $client->listObjects(['Bucket' => $bucketname]); + $objects = $objectsListResponse['Contents'] ?? []; + foreach ($objects as $object) { + echo $object['Key'] . "\t" . $object['Size'] . "\t" . $object['LastModified'] . "\n"; } .. note:: If there are more than 1000 objects in this bucket, - you need to check $ObjectListResponse->body->isTruncated + you need to check $objectsListResponse['isTruncated'] and run again with the name of the last key listed. Keep doing this until isTruncated is not true. @@ -107,7 +115,7 @@ Deleting a Bucket ----------------- This deletes the bucket called ``my-old-bucket`` and returns a -``CFResponse`` object +``AWS\Result`` object .. note:: @@ -116,18 +124,7 @@ This deletes the bucket called ``my-old-bucket`` and returns a .. code-block:: php delete_bucket('my-old-bucket'); - - -Forced Delete for Non-empty Buckets ------------------------------------ - -This will delete the bucket even if it is not empty. - -.. code-block:: php - - delete_bucket('my-old-bucket', 1); + $client->deleteBucket(['Bucket' => 'my-old-bucket']); Creating an Object @@ -138,9 +135,11 @@ This creates an object ``hello.txt`` with the string ``"Hello World!"`` .. code-block:: php create_object('my-bucket-name', 'hello.txt', array( - 'body' => "Hello World!", - )); + $client->putObject([ + 'Bucket' => 'my-bucket-name', + 'Key' => 'hello.txt', + 'Body' => "Hello World!" + ]); Change an Object's ACL @@ -152,8 +151,16 @@ This makes the object ``hello.txt`` to be publicly readable and .. code-block:: php set_object_acl('my-bucket-name', 'hello.txt', AmazonS3::ACL_PUBLIC); - $Connection->set_object_acl('my-bucket-name', 'secret_plans.txt', AmazonS3::ACL_PRIVATE); + $client->putObjectAcl([ + 'Bucket' => 'my-bucket-name', + 'Key' => 'hello.txt', + 'ACL' => 'public-read' + ]); + $client->putObjectAcl([ + 'Bucket' => 'my-bucket-name', + 'Key' => 'secret_plans.txt', + 'ACL' => 'private' + ]); Delete an Object @@ -164,7 +171,7 @@ This deletes the object ``goodbye.txt`` .. code-block:: php delete_object('my-bucket-name', 'goodbye.txt'); + $client->deleteObject(['Bucket' => 'my-bucket-name', 'Key' => 'goodbye.txt']); Download an Object (to a file) @@ -176,11 +183,8 @@ This downloads the object ``poetry.pdf`` and saves it in .. code-block:: php get_object('my-bucket-name', 'poetry.pdf', array( - 'fileDownload' => $FileHandle, - )); - + $object = $client->getObject(['Bucket' => 'my-bucket-name', 'Key' => 'poetry.pdf']); + file_put_contents('/home/larry/documents/poetry.pdf', $object['Body']->getContents()); Generate Object Download URLs (signed and unsigned) --------------------------------------------------- @@ -196,13 +200,15 @@ the URL will stop working). .. code-block:: php get_object_url('my-bucket-name', 'hello.txt'); - echo $plans_url . "\n"; - my $secret_url = $Connection->get_object_url('my-bucket-name', 'secret_plans.txt', '1 hour'); - echo $secret_url . "\n"; + $hello_url = $client->getObjectUrl('my-bucket-name', 'hello.txt'); + echo $hello_url."\n"; + + $secret_plans_cmd = $client->getCommand('GetObject', ['Bucket' => 'my-bucket-name', 'Key' => 'secret_plans.txt']); + $request = $client->createPresignedRequest($secret_plans_cmd, '+1 hour'); + echo $request->getUri()."\n"; The output of this will look something like:: http://objects.dreamhost.com/my-bucket-name/hello.txt - http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX + http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=sandboxAccessKey%2F20190116%2F%2Fs3%2Faws4_request&X-Amz-Date=20190116T125520Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=61921f07c73d7695e47a2192cf55ae030f34c44c512b2160bb5a936b2b48d923 -- 2.47.3