s3_storage/vendor/akeeba/s3/README.md

   1 # Akeeba Amazon S3 Connector
   2
   3 A compact, dependency-less Amazon S3 API client implementing the most commonly used features
   4
   5 ## Why reinvent the wheel
   6
   7 After having a lot of impossible to debug problems with Amazon's Guzzle-based AWS SDK we decided to roll our own connector for Amazon S3. This is by no means a complete implementation, just a small subset of S3's features which are required by our software. The design goals are simplicity, no external dependencies and low memory footprint.
   8
   9 This code was originally based on [S3.php written by Donovan Schonknecht](http://undesigned.org.za/2007/10/22/amazon-s3-php-class) which is available under a BSD-like license. This repository no longer reflects the original author's work and should not be confused with it.
  10
  11 This software is distributed under the GNU General Public License version 3 or, at your option, any later version published by the Free Software Foundation (FSF). In short, it's "GPLv3+".
  12
  13 ## Important note about version 2
  14
  15 Akeeba Amazon S3 Connector version 2 has dropped support for PPH 5.3 to 7.0 inclusive. It is only compatible with PHP 7.1 or later, up to and including PHP 8.0.
  16
  17 The most significant change in this version is that all methods use scalar type hints for parameters and return values. This _may_ break existing consumers which relied on implicit type conversion e.g. passing strings containing integer values instead of _actual_ integer values.
  18
  19 ## Using the connector
  20
  21 ### Get a connector object
  22
  23 ```php
  24 $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
  25         'YourAmazonAccessKey',
  26         'YourAmazonSecretKey'
  27 );
  28
  29 $connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
  30 ```
  31
  32 If you are running inside an Amazon EC2 instance you can fetch temporary credentials from the instance's metadata
  33 server using the IAM Role attached to the EC2 instance. In this case you need to do this (169.254.169.254 is a fixed
  34 IP hosting the instance's metadata cache service):
  35
  36 ```php
  37 $role = file_get_contents('http://169.254.169.254/latest/meta-data/iam/security-credentials/');
  38 $jsonCredentials = file_get_contents('http://169.254.169.254/latest/meta-data/iam/security-credentials/' . $role);
  39 $credentials = json_decode($jsonCredentials, true);
  40 $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
  41         $credentials['AccessKeyId'],
  42         $credentials['SecretAccessKey'],
  43         'v4',
  44         $yourRegion
  45 );
  46 $configuration->setToken($credentials['Token']);
  47
  48 $connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
  49 ```
  50
  51 where `$yourRegion` is the AWS region of your bucket, e.g. `us-east-1`. Please note that we are passing the security
  52 token (`$credentials['Token']`) to the Configuration object. This is REQUIRED. The temporary credentials returned by
  53 the metadata service won't work without it.
  54
  55 Also worth noting is that the temporary credentials don't last forever. Check the `$credentials['Expiration']` to see
  56 when they are about to expire. Amazon recommends that you retry fetching new credentials from the metadata service
  57 10 minutes before your cached credentials are set to expire. The metadata service is guaranteed to provision fresh
  58 temporary credentials by that time.
  59
  60 ### Listing buckets
  61
  62 ```php
  63 $listing = $connector->listBuckets(true);
  64 ```
  65
  66 Returns an array like this:
  67
  68 ```
  69 array(2) {
  70   'owner' =>
  71   array(2) {
  72     'id' =>
  73     string(64) "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  74     'name' =>
  75     string(8) "someUserName"
  76   }
  77   'buckets' =>
  78   array(3) {
  79     [0] =>
  80     array(2) {
  81       'name' =>
  82       string(10) "mybucket"
  83       'time' =>
  84       int(1267730711)
  85     }
  86     [1] =>
  87     array(2) {
  88       'name' =>
  89       string(10) "anotherbucket"
  90       'time' =>
  91       int(1269516249)
  92     }
  93     [2] =>
  94     array(2) {
  95       'name' =>
  96       string(11) "differentbucket"
  97       'time' =>
  98       int(1354458048)
  99     }
 100   }
 101 }
 102 ```
 103
 104 ### Listing bucket contents
 105
 106 ```php
 107 $listing = $connector->getBucket('mybucket', 'path/to/list/');
 108 ```
 109
 110 If you want to list "subdirectories" you need to do
 111
 112 ```php
 113 $listing = $connector->getBucket('mybucket', 'path/to/list/', null, null, '/', true);
 114 ```
 115
 116 The last parameter (common prefixes) controls the listing of "subdirectories"
 117
 118 ### Uploading (small) files
 119
 120 From a file:
 121
 122 ```php
 123 $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
 124 $connector->putObject($input, 'mybucket', 'path/to/myfile.txt');
 125 ```
 126
 127 From a string:
 128
 129 ```php
 130 $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromData($sourceString);
 131 $connector->putObject($input, 'mybucket', 'path/to/myfile.txt');
 132 ```
 133
 134 From a stream resource:
 135
 136 ```php
 137 $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromResource($streamHandle, false);
 138 $connector->putObject($input, 'mybucket', 'path/to/myfile.txt');
 139 ```
 140
 141 In all cases the entirety of the file has to be loaded in memory.
 142
 143 ### Uploading large file with multipart (chunked) uploads
 144
 145 Files are uploaded in 5Mb chunks.
 146
 147 ```php
 148 $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
 149 $uploadId = $connector->startMultipart($input, 'mybucket', 'mypath/movie.mov');
 150
 151 $eTags = array();
 152 $eTag = null;
 153 $partNumber = 0;
 154
 155 do
 156 {
 157         // IMPORTANT: You MUST create the input afresh before each uploadMultipart call
 158         $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
 159         $input->setUploadID($uploadId);
 160         $input->setPartNumber(++$partNumber);
 161
 162         $eTag = $connector->uploadMultipart($input, 'mybucket', 'mypath/movie.mov');
 163
 164         if (!is_null($eTag))
 165         {
 166                 $eTags[] = $eTag;
 167         }
 168 }
 169 while (!is_null($eTag));
 170
 171 // IMPORTANT: You MUST create the input afresh before finalising the multipart upload
 172 $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
 173 $input->setUploadID($uploadId);
 174 $input->setEtags($eTags);
 175
 176 $connector->finalizeMultipart($input, 'mybucket', 'mypath/movie.mov');
 177 ```
 178
 179 As long as you keep track of the UploadId, PartNumber and ETags you can have each uploadMultipart call in a separate
 180 page load to prevent timeouts.
 181
 182 ### Get presigned URLs
 183
 184 Allows browsers to download files directly without exposing your credentials and without going through your server:
 185
 186 ```php
 187 $preSignedURL = $connector->getAuthenticatedURL('mybucket', 'path/to/file.jpg', 60);
 188 ```
 189
 190 The last parameter controls how many seconds into the future this URL will be valid.
 191
 192 ### Download
 193
 194 To a file with absolute path `$targetFile`
 195
 196 ```php
 197 $connector->getObject('mybucket', 'path/to/file.jpg', $targetFile);
 198 ```
 199
 200 To a string
 201
 202 ```php
 203 $content = $connector->getObject('mybucket', 'path/to/file.jpg', false);
 204 ```
 205
 206 ### Delete an object
 207
 208 ```php
 209 $connector->deleteObject('mybucket', 'path/to/file.jpg');
 210 ```
 211
 212 ## Configuration options
 213
 214 The Configuration option has optional methods which can be used to enable some useful features in the connector.
 215
 216 You need to execute these methods against the Configuration object before passing it to the Connector's constructor. For example:
 217
 218 ```php
 219 $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
 220         'YourAmazonAccessKey',
 221         'YourAmazonSecretKey'
 222 );
 223
 224 // Use v4 signatures and Dualstack URLs
 225 $configuration->setSignatureMethod('v4');
 226 $configuration->setUseDualstackUrl(true);
 227
 228 $connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
 229 ```
 230
 231 ### HTTPS vs plain HTTP
 232
 233 **It is not recommended to use plain HTTP connections to Amazon S3**. If, however, you have no other option you can tell the Configuration object to use plain HTTP URLs:
 234
 235 ```php
 236 $configuration->setSSL(false);
 237 ```
 238
 239 ### Custom endpoint
 240
 241 You can use the Akeeba Amazon S3 Connector library with S3-compatible APIs such as DigitalOcean's Spaces by changing the endpoint URL.
 242
 243 Please note that if the S3-compatible APi uses v4 signatures you need to enter the region-specific endpoint domain name and the region when initializing the object, e.g.:
 244
 245 ```php
 246 // DigitalOcean Spaces using v4 signatures
 247 // The access credentials are those used in the example at https://developers.digitalocean.com/documentation/spaces/
 248 $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
 249         '532SZONTQ6ALKBCU94OU',
 250         'zCkY83KVDXD8u83RouEYPKEm/dhPSPB45XsfnWj8fxQ',
 251     'v4',
 252     'nyc3'
 253 );
 254 $configuration->setEndpoint('nyc3.digitaloceanspaces.com');
 255
 256 $connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
 257 ```
 258
 259 If your S3-compatible API uses v2 signatures you do not need to specify a region.
 260
 261 ```php
 262 // DigitalOcean Spaces using v2 signatures
 263 // The access credentials are those used in the example at https://developers.digitalocean.com/documentation/spaces/
 264 $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
 265         '532SZONTQ6ALKBCU94OU',
 266         'zCkY83KVDXD8u83RouEYPKEm/dhPSPB45XsfnWj8fxQ',
 267     'v2'
 268 );
 269 $configuration->setEndpoint('nyc3.digitaloceanspaces.com');
 270
 271 $connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
 272 ```
 273
 274 ### Legacy path-style access
 275
 276 The S3 API calls made by this library will use by default the subdomain-style access. That is to say, the endpoint will be prefixed with the name of the bucket. For example, a bucket called `example` in the `eu-west-1` region will be accessed using the endpoint URL `example.s3.eu-west-1.amazonaws.com`.
 277
 278 If you have buckets with characters that are invalid in the context of DNS (most notably dots and uppercase characters) this will fail. You will need to use the legacy path style instead. In this case the endpoint used is the generic region specific one (`s3.eu-west-1.amazonaws.com` in our example above) and the API URL will be prefixed with the bucket name.
 279
 280 You need to do:
 281 ```php
 282 $configuration->setUseLegacyPathStyle(true);
 283 ```
 284
 285 Caveat: this will not work with v2 signatures if you are using Amazon AWS S3 proper. It will work with the v2 signatures if you are using a custom endpoint, though. In fact, most S3-compatible APIs implementing V2 signatures _expect_ you to use path-style access.
 286
 287 ### Dualstack (IPv4 and IPv6) support
 288
 289 Amazon S3 supports dual-stack URLs which resolve to both IPv4 and IPv6 addresses. By default they are _not_ used. If you want to enable this feature you need to do:
 290
 291 ```php
 292 $connector->setUseDualstackUrl(true);
 293 ```
 294
 295 Caveat: this option only takes effect if you are using Amazon S3 proper. It will _not_ have any effect with custom endpoints.