## Why reinvent the wheel
-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.
+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 a low memory footprint.
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.
-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+".
+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 GPL-3.0-or-later, as noted in composer.json.
-## Important note about version 2
+## Important notes about version 2
-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.
+### PHP version support since 2.0
-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.
+Akeeba Amazon S3 Connector version 2 has dropped support for PHP 5.3 to 7.0 inclusive.
+
+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.
+
+### Namespace change since 2.3
+
+Up to and including version 2.2 of the library, the namespace was `\Akeeba\Engine\Postproc\Connector\S3v4`. From version 2.3 of the library the namespace has changed to `\Akeeba\S3`.
+
+The library automatically registers aliases of the old classes to the new ones, thus ensuring updating the library will not introduce backwards incompatible changes. This is why it's not a major version update. Aliases will remain in place until at least version 3.0 of the library.
## Using the connector
+You need to define a constant before using or referencing any class in the library:
+
+```php
+defined('AKEEBAENGINE') or define('AKEEBAENGINE', 1);
+```
+
+All library files have a line similar to
+
+```php
+defined('AKEEBAENGINE') or die();
+```
+
+to prevent direct access to the libraries files. This is intentional. The primary use case for this library is mass-distributed software which gets installed in a publicly accessible subdirectory of the web root. This line prevents any accidental path disclosure from PHP error messages if someone were to access these files directly on misconfigured servers.
+
+If you are writing a Joomla extension, especially a plugin or module, please _always_ check if the constant has already been defined before defining it yourself. Thank you!
+
### Get a connector object
```php
-$configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
+$configuration = new \Akeeba\S3\Configuration(
'YourAmazonAccessKey',
'YourAmazonSecretKey'
);
-$connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
+$connector = new \Akeeba\S3\Connector($configuration);
```
If you are running inside an Amazon EC2 instance you can fetch temporary credentials from the instance's metadata
$role = file_get_contents('http://169.254.169.254/latest/meta-data/iam/security-credentials/');
$jsonCredentials = file_get_contents('http://169.254.169.254/latest/meta-data/iam/security-credentials/' . $role);
$credentials = json_decode($jsonCredentials, true);
-$configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
+$configuration = new \Akeeba\S3\Configuration(
$credentials['AccessKeyId'],
$credentials['SecretAccessKey'],
'v4',
);
$configuration->setToken($credentials['Token']);
-$connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
+$connector = new \Akeeba\S3\Connector($configuration);
```
where `$yourRegion` is the AWS region of your bucket, e.g. `us-east-1`. Please note that we are passing the security
token (`$credentials['Token']`) to the Configuration object. This is REQUIRED. The temporary credentials returned by
the metadata service won't work without it.
-Also worth noting is that the temporary credentials don't last forever. Check the `$credentials['Expiration']` to see
+Another point worth noting is that the temporary credentials don't last forever. Check the `$credentials['Expiration']` to see
when they are about to expire. Amazon recommends that you retry fetching new credentials from the metadata service
10 minutes before your cached credentials are set to expire. The metadata service is guaranteed to provision fresh
temporary credentials by that time.
From a file:
```php
-$input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
+$input = \Akeeba\S3\Input::createFromFile($sourceFile);
$connector->putObject($input, 'mybucket', 'path/to/myfile.txt');
```
From a string:
```php
-$input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromData($sourceString);
+$input = \Akeeba\S3\Input::createFromData($sourceString);
$connector->putObject($input, 'mybucket', 'path/to/myfile.txt');
```
From a stream resource:
```php
-$input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromResource($streamHandle, false);
+$input = \Akeeba\S3\Input::createFromResource($streamHandle, false);
$connector->putObject($input, 'mybucket', 'path/to/myfile.txt');
```
Files are uploaded in 5Mb chunks.
```php
-$input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
+$input = \Akeeba\S3\Input::createFromFile($sourceFile);
$uploadId = $connector->startMultipart($input, 'mybucket', 'mypath/movie.mov');
$eTags = array();
do
{
// IMPORTANT: You MUST create the input afresh before each uploadMultipart call
- $input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
+ $input = \Akeeba\S3\Input::createFromFile($sourceFile);
$input->setUploadID($uploadId);
$input->setPartNumber(++$partNumber);
while (!is_null($eTag));
// IMPORTANT: You MUST create the input afresh before finalising the multipart upload
-$input = \Akeeba\Engine\Postproc\Connector\S3v4\Input::createFromFile($sourceFile);
+$input = \Akeeba\S3\Input::createFromFile($sourceFile);
$input->setUploadID($uploadId);
$input->setEtags($eTags);
$connector->deleteObject('mybucket', 'path/to/file.jpg');
```
+### Test if an object exists
+
+```php
+try
+{
+ $headers = $connector->headObject('mybucket', 'path/to/file.jpg');
+ $exists = true;
+}
+catch (\Akeeba\S3\Exception\CannotGetFile $e)
+{
+ $headers = [];
+ $exists = false;
+}
+```
+
+The `$headers` variable contains an array with the S3 headers returned by the [HeadObject(https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) API call. The header keys are always in lowercase. Please note that _not all_ of the headers Amazon describes in their documentation are returned in every request.
+
## Configuration options
The Configuration option has optional methods which can be used to enable some useful features in the connector.
You need to execute these methods against the Configuration object before passing it to the Connector's constructor. For example:
```php
-$configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
+$configuration = new \Akeeba\S3\Configuration(
'YourAmazonAccessKey',
'YourAmazonSecretKey'
);
$configuration->setSignatureMethod('v4');
$configuration->setUseDualstackUrl(true);
-$connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
+$connector = new \Akeeba\S3\Connector($configuration);
```
### HTTPS vs plain HTTP
```php
// DigitalOcean Spaces using v4 signatures
// The access credentials are those used in the example at https://developers.digitalocean.com/documentation/spaces/
-$configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
+$configuration = new \Akeeba\S3\Configuration(
'532SZONTQ6ALKBCU94OU',
'zCkY83KVDXD8u83RouEYPKEm/dhPSPB45XsfnWj8fxQ',
'v4',
);
$configuration->setEndpoint('nyc3.digitaloceanspaces.com');
-$connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
+$connector = new \Akeeba\S3\Connector($configuration);
```
If your S3-compatible API uses v2 signatures you do not need to specify a region.
```php
// DigitalOcean Spaces using v2 signatures
// The access credentials are those used in the example at https://developers.digitalocean.com/documentation/spaces/
-$configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
+$configuration = new \Akeeba\S3\Configuration(
'532SZONTQ6ALKBCU94OU',
'zCkY83KVDXD8u83RouEYPKEm/dhPSPB45XsfnWj8fxQ',
'v2'
);
$configuration->setEndpoint('nyc3.digitaloceanspaces.com');
-$connector = new \Akeeba\Engine\Postproc\Connector\S3v4\Connector($configuration);
+$connector = new \Akeeba\S3\Connector($configuration);
```
### Legacy path-style access
$configuration->setUseLegacyPathStyle(true);
```
-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.
+Caveat: this will not work with v2 signatures if you are using Amazon AWS S3 proper. It will very likely work with the v2 signatures if you are using a custom endpoint, though.
### Dualstack (IPv4 and IPv6) support
projects / friendica-addons.git / blobdiff