friendica/friendica-addons
1
0
Fork 0
mirror of https://git.friendi.ca/friendica/friendica-addons.git synced 2025-07-13 20:08:49 +00:00
Code Issues Releases Wiki Activity

[s3_storage] Bump version of akeeba/s3 to version 2.3.1

Browse source 
- Address https://github.com/friendica/friendica/issues/12011#issuecomment-1854681792
This commit is contained in:
Hypolite Petovan 2023-12-18 21:28:16 -05:00
parent 9daa11eb10
commit 3e74af9775
61 changed files with 1472 additions and 708 deletions
Download patch file Download diff file Expand all files Collapse all files

87
s3_storage/vendor/akeeba/s3/README.md vendored
View file

@ -4,29 +4,53 @@ A compact, dependency-less Amazon S3 API client implementing the most commonly u
## 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
@ -37,7 +61,7 @@ IP hosting the instance's metadata cache service):
$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',
@ -45,14 +69,14 @@ $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
);
$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.
@ -120,21 +144,21 @@ The last parameter (common prefixes) controls the listing of "subdirectories"
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');
```
@ -145,7 +169,7 @@ In all cases the entirety of the file has to be loaded in memory.
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();
@ -155,7 +179,7 @@ $partNumber = 0;
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);
@ -169,7 +193,7 @@ do
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);
@ -209,6 +233,23 @@ $content = $connector->getObject('mybucket', 'path/to/file.jpg', false);
$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.
@ -216,7 +257,7 @@ The Configuration option has optional methods which can be used to enable some u
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'
);
@ -225,7 +266,7 @@ $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
$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
@ -245,7 +286,7 @@ Please note that if the S3-compatible APi uses v4 signatures you need to enter t
```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',
@ -253,7 +294,7 @@ $configuration = new \Akeeba\Engine\Postproc\Connector\S3v4\Configuration(
);
$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.
@ -261,14 +302,14 @@ 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
@ -282,7 +323,7 @@ You need to do:
$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