ceph/doc/radosgw/s3/php.rst

   1 .. _php:
   2
   3 PHP S3 Examples
   4 ===============
   5
   6 Installing AWS PHP SDK
   7 ----------------------
   8
   9 This installs AWS PHP SDK using composer (see here_ how to install composer).
  10
  11 .. _here: https://getcomposer.org/download/
  12
  13 .. code-block:: bash
  14
  15         $ composer install aws/aws-sdk-php
  16
  17 Creating a Connection
  18 ---------------------
  19
  20 This creates a connection so that you can interact with the server.
  21
  22 .. note::
  23
  24    The client initialization requires a region so we use ``''``.
  25
  26 .. code-block:: php
  27
  28         <?php
  29
  30         use Aws\S3\S3Client;
  31
  32         define('AWS_KEY', 'place access key here');
  33         define('AWS_SECRET_KEY', 'place secret key here');
  34         $ENDPOINT = 'http://objects.dreamhost.com';
  35
  36         // require the amazon sdk from your composer vendor dir
  37         require __DIR__.'/vendor/autoload.php';
  38
  39         // Instantiate the S3 class and point it at the desired host
  40         $client = new S3Client([
  41             'region' => '',
  42             'version' => '2006-03-01',
  43             'endpoint' => $ENDPOINT,
  44             'credentials' => [
  45                 'key' => AWS_KEY,
  46                 'secret' => AWS_SECRET_KEY
  47             ],
  48             // Set the S3 class to use objects.dreamhost.com/bucket
  49             // instead of bucket.objects.dreamhost.com
  50             'use_path_style_endpoint' => true
  51         ]);
  52
  53 Listing Owned Buckets
  54 ---------------------
  55 This gets a ``AWS\Result`` instance that is more convenient to visit using array access way.
  56 This also prints out the bucket name and creation date of each bucket.
  57
  58 .. code-block:: php
  59
  60         <?php
  61         $listResponse = $client->listBuckets();
  62         $buckets = $listResponse['Buckets'];
  63         foreach ($buckets as $bucket) {
  64             echo $bucket['Name'] . "\t" . $bucket['CreationDate'] . "\n";
  65         }
  66
  67 The output will look something like this::
  68
  69    mahbuckat1   2011-04-21T18:05:39.000Z
  70    mahbuckat2   2011-04-21T18:05:48.000Z
  71    mahbuckat3   2011-04-21T18:07:18.000Z
  72
  73
  74 Creating a Bucket
  75 -----------------
  76
  77 This creates a new bucket called ``my-new-bucket`` and returns a
  78 ``AWS\Result`` object.
  79
  80 .. code-block:: php
  81
  82         <?php
  83         $client->createBucket(['Bucket' => 'my-new-bucket']);
  84
  85
  86 List a Bucket's Content
  87 -----------------------
  88
  89 This gets a ``AWS\Result`` instance that is more convenient to visit using array access way.
  90 This then prints out each object's name, the file size, and last modified date.
  91
  92 .. code-block:: php
  93
  94         <?php
  95         $objectsListResponse = $client->listObjects(['Bucket' => $bucketname]);
  96         $objects = $objectsListResponse['Contents'] ?? [];
  97         foreach ($objects as $object) {
  98             echo $object['Key'] . "\t" . $object['Size'] . "\t" . $object['LastModified'] . "\n";
  99         }
 100
 101 .. note::
 102
 103    If there are more than 1000 objects in this bucket,
 104    you need to check $objectsListResponse['isTruncated']
 105    and run again with the name of the last key listed.
 106    Keep doing this until isTruncated is not true.
 107
 108 The output will look something like this if the bucket has some files::
 109
 110    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
 111    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
 112
 113
 114 Deleting a Bucket
 115 -----------------
 116
 117 This deletes the bucket called ``my-old-bucket`` and returns a
 118 ``AWS\Result`` object
 119
 120 .. note::
 121
 122    The Bucket must be empty! Otherwise it won't work!
 123
 124 .. code-block:: php
 125
 126         <?php
 127         $client->deleteBucket(['Bucket' => 'my-old-bucket']);
 128
 129
 130 Creating an Object
 131 ------------------
 132
 133 This creates an object ``hello.txt`` with the string ``"Hello World!"``
 134
 135 .. code-block:: php
 136
 137         <?php
 138         $client->putObject([
 139             'Bucket' => 'my-bucket-name',
 140             'Key' => 'hello.txt',
 141             'Body' => "Hello World!"
 142         ]);
 143
 144
 145 Change an Object's ACL
 146 ----------------------
 147
 148 This makes the object ``hello.txt`` to be publicly readable and
 149 ``secret_plans.txt`` to be private.
 150
 151 .. code-block:: php
 152
 153         <?php
 154         $client->putObjectAcl([
 155             'Bucket' => 'my-bucket-name',
 156             'Key' => 'hello.txt',
 157             'ACL' => 'public-read'
 158         ]);
 159         $client->putObjectAcl([
 160             'Bucket' => 'my-bucket-name',
 161             'Key' => 'secret_plans.txt',
 162             'ACL' => 'private'
 163         ]);
 164
 165
 166 Delete an Object
 167 ----------------
 168
 169 This deletes the object ``goodbye.txt``
 170
 171 .. code-block:: php
 172
 173         <?php
 174         $client->deleteObject(['Bucket' => 'my-bucket-name', 'Key' => 'goodbye.txt']);
 175
 176
 177 Download an Object (to a file)
 178 ------------------------------
 179
 180 This downloads the object ``poetry.pdf`` and saves it in
 181 ``/home/larry/documents/``
 182
 183 .. code-block:: php
 184
 185         <?php
 186         $object = $client->getObject(['Bucket' => 'my-bucket-name', 'Key' => 'poetry.pdf']);
 187         file_put_contents('/home/larry/documents/poetry.pdf', $object['Body']->getContents());
 188
 189 Generate Object Download URLs (signed and unsigned)
 190 ---------------------------------------------------
 191
 192 This generates an unsigned download URL for ``hello.txt``.
 193 This works because we made ``hello.txt`` public by setting
 194 the ACL above. This then generates a signed download URL
 195 for ``secret_plans.txt`` that will work for 1 hour.
 196 Signed download URLs will work for the time period even
 197 if the object is private (when the time period is up,
 198 the URL will stop working).
 199
 200 .. code-block:: php
 201
 202         <?php
 203         $hello_url = $client->getObjectUrl('my-bucket-name', 'hello.txt');
 204         echo $hello_url."\n";
 205
 206         $secret_plans_cmd = $client->getCommand('GetObject', ['Bucket' => 'my-bucket-name', 'Key' => 'secret_plans.txt']);
 207         $request = $client->createPresignedRequest($secret_plans_cmd, '+1 hour');
 208         echo $request->getUri()."\n";
 209
 210 The output of this will look something like::
 211
 212    http://objects.dreamhost.com/my-bucket-name/hello.txt
 213    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
 214