src/ceph/doc/radosgw/s3/php.rst

   1 .. _php:
   2
   3 PHP S3 Examples
   4 ===============
   5
   6 Creating a Connection
   7 ---------------------
   8
   9 This creates a connection so that you can interact with the server.
  10
  11 .. code-block:: php
  12
  13         <?php
  14         define('AWS_KEY', 'place access key here');
  15         define('AWS_SECRET_KEY', 'place secret key here');
  16         define('AWS_CANONICAL_ID', 'your DHO Username');
  17         define('AWS_CANONICAL_NAME', 'Also your DHO Username!');
  18         $HOST = 'objects.dreamhost.com';
  19
  20         // require the amazon sdk for php library
  21         require_once 'AWSSDKforPHP/sdk.class.php';
  22
  23         // Instantiate the S3 class and point it at the desired host
  24         $Connection = new AmazonS3(array(
  25                 'key' => AWS_KEY,
  26                 'secret' => AWS_SECRET_KEY,
  27                 'canonical_id' => AWS_CANONICAL_ID,
  28                 'canonical_name' => AWS_CANONICAL_NAME,
  29         ));
  30         $Connection->set_hostname($HOST);
  31         $Connection->allow_hostname_override(false);
  32
  33         // Set the S3 class to use objects.dreamhost.com/bucket
  34         // instead of bucket.objects.dreamhost.com
  35         $Connection->enable_path_style();
  36
  37
  38 Listing Owned Buckets
  39 ---------------------
  40 This gets a list of CFSimpleXML objects representing buckets that you
  41 own.  This also prints out the bucket name and creation date of each
  42 bucket.
  43
  44 .. code-block:: php
  45
  46         <?php
  47         $ListResponse = $Connection->list_buckets();
  48         $Buckets = $ListResponse->body->Buckets->Bucket;
  49         foreach ($Buckets as $Bucket) {
  50                 echo $Bucket->Name . "\t" . $Bucket->CreationDate . "\n";
  51         }
  52
  53 The output will look something like this::
  54
  55    mahbuckat1   2011-04-21T18:05:39.000Z
  56    mahbuckat2   2011-04-21T18:05:48.000Z
  57    mahbuckat3   2011-04-21T18:07:18.000Z
  58
  59
  60 Creating a Bucket
  61 -----------------
  62
  63 This creates a new bucket called ``my-new-bucket`` and returns a
  64 ``CFResponse`` object.
  65
  66 .. note::
  67
  68    This command requires a region as the second argument,
  69    so we use ``AmazonS3::REGION_US_E1``, because this constant is ``''``
  70
  71 .. code-block:: php
  72
  73         <?php
  74         $Connection->create_bucket('my-new-bucket', AmazonS3::REGION_US_E1);
  75
  76
  77 List a Bucket's Content
  78 -----------------------
  79
  80 This gets an array of ``CFSimpleXML`` objects representing the objects
  81 in the bucket. This then prints out each object's name, the file size,
  82 and last modified date.
  83
  84 .. code-block:: php
  85
  86         <?php
  87         $ObjectsListResponse = $Connection->list_objects($bucketname);
  88         $Objects = $ObjectsListResponse->body->Contents;
  89         foreach ($Objects as $Object) {
  90                 echo $Object->Key . "\t" . $Object->Size . "\t" . $Object->LastModified . "\n";
  91         }
  92
  93 .. note::
  94
  95    If there are more than 1000 objects in this bucket,
  96    you need to check $ObjectListResponse->body->isTruncated
  97    and run again with the name of the last key listed.
  98    Keep doing this until isTruncated is not true.
  99
 100 The output will look something like this if the bucket has some files::
 101
 102    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
 103    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
 104
 105
 106 Deleting a Bucket
 107 -----------------
 108
 109 This deletes the bucket called ``my-old-bucket`` and returns a
 110 ``CFResponse`` object
 111
 112 .. note::
 113
 114    The Bucket must be empty! Otherwise it won't work!
 115
 116 .. code-block:: php
 117
 118         <?php
 119         $Connection->delete_bucket('my-old-bucket');
 120
 121
 122 Forced Delte for Non-empty Buckets
 123 ----------------------------------
 124
 125 This will delete the bucket even if it is not empty.
 126
 127 .. code-block:: php
 128
 129         <?php
 130         $Connection->delete_bucket('my-old-bucket', 1);
 131
 132
 133 Creating an Object
 134 ------------------
 135
 136 This creates an object ``hello.txt`` with the string ``"Hello World!"``
 137
 138 .. code-block:: php
 139
 140         <?php
 141         $Connection->create_object('my-bucket-name', 'hello.txt', array(
 142                 'body' => "Hello World!",
 143         ));
 144
 145
 146 Change an Object's ACL
 147 ----------------------
 148
 149 This makes the object ``hello.txt`` to be publicly readable and
 150 ``secret_plans.txt`` to be private.
 151
 152 .. code-block:: php
 153
 154         <?php
 155         $Connection->set_object_acl('my-bucket-name', 'hello.txt', AmazonS3::ACL_PUBLIC);
 156         $Connection->set_object_acl('my-bucket-name', 'secret_plans.txt', AmazonS3::ACL_PRIVATE);
 157
 158
 159 Delete an Object
 160 ----------------
 161
 162 This deletes the object ``goodbye.txt``
 163
 164 .. code-block:: php
 165
 166         <?php
 167         $Connection->delete_object('my-bucket-name', 'goodbye.txt');
 168
 169
 170 Download an Object (to a file)
 171 ------------------------------
 172
 173 This downloads the object ``poetry.pdf`` and saves it in
 174 ``/home/larry/documents/``
 175
 176 .. code-block:: php
 177
 178         <?php
 179         $FileHandle = fopen('/home/larry/documents/poetry.pdf', 'w+');
 180         $Connection->get_object('my-bucket-name', 'poetry.pdf', array(
 181                 'fileDownload' => $FileHandle,
 182         ));
 183
 184
 185 Generate Object Download URLs (signed and unsigned)
 186 ---------------------------------------------------
 187
 188 This generates an unsigned download URL for ``hello.txt``.
 189 This works because we made ``hello.txt`` public by setting
 190 the ACL above. This then generates a signed download URL
 191 for ``secret_plans.txt`` that will work for 1 hour.
 192 Signed download URLs will work for the time period even
 193 if the object is private (when the time period is up,
 194 the URL will stop working).
 195
 196 .. code-block:: php
 197
 198         <?php
 199         my $plans_url = $Connection->get_object_url('my-bucket-name', 'hello.txt');
 200         echo $plans_url . "\n";
 201         my $secret_url = $Connection->get_object_url('my-bucket-name', 'secret_plans.txt', '1 hour');
 202         echo $secret_url . "\n";
 203
 204 The output of this will look something like::
 205
 206    http://objects.dreamhost.com/my-bucket-name/hello.txt
 207    http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 208