[s3_storage] Update Composer dependency ahead of release

- Updating akeeba/s3 (2.3.1 => 2.3.2)
This commit is contained in:
Hypolite Petovan 2024-03-19 23:03:34 -04:00
parent c6b2ed96d7
commit d910502a17
53 changed files with 583 additions and 206 deletions

View file

@ -1,6 +1,8 @@
# Akeeba Amazon S3 Connector
A compact, dependency-less Amazon S3 API client implementing the most commonly used features
A compact, dependency-less Amazon S3 API client implementing the most commonly used features.
This library is designed to work with Amazon S3 proper, as well as S3-compatible services such as but not limited to Wasabi, Google Storage, Synology C2, ExoScale etc.
## Why reinvent the wheel
@ -275,7 +277,9 @@ $connector = new \Akeeba\S3\Connector($configuration);
```php
$configuration->setSSL(false);
```
```
Caveat: HTTPS will only work if PHP can verify the TLS certificate of your endpoint. This may not be the case when using a local testing service (e.g. LocalStack), or for some buckets with dots in their names. Moreover, if you are on Windows, do note that neither PHP comes with a Certification Authority cache, nor is there a system-wide CA cache; you'll have to [download](https://curl.se/docs/caextract.html) it and configure PHP, or use [composer/ca-bundle](https://packagist.org/packages/composer/ca-bundle) in your `composer.json` file.
### Custom endpoint
@ -293,6 +297,8 @@ $configuration = new \Akeeba\S3\Configuration(
'nyc3'
);
$configuration->setEndpoint('nyc3.digitaloceanspaces.com');
$configuration->setRegion('nyc3');
$configuration->setSignatureMethod('v4');
$connector = new \Akeeba\S3\Connector($configuration);
```
@ -312,18 +318,22 @@ $configuration->setEndpoint('nyc3.digitaloceanspaces.com');
$connector = new \Akeeba\S3\Connector($configuration);
```
Caveat: Setting the endpoint resets the signature version and region. This is why you need to set them _a second time_, after setting the endpoint, as seen in the first example above.
### Legacy path-style access
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`.
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.
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.
You need to do:
```php
$configuration->setUseLegacyPathStyle(true);
```
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.
Caveats:
* 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.
* This option has no effect on pre-authorised (pre-signed) URLs. Legacy path-style access is used for these URLs by default.
### Dualstack (IPv4 and IPv6) support
@ -333,4 +343,26 @@ Amazon S3 supports dual-stack URLs which resolve to both IPv4 and IPv6 addresses
$connector->setUseDualstackUrl(true);
```
Caveat: this option only takes effect if you are using Amazon S3 proper. It will _not_ have any effect with custom endpoints.
Caveat: This option only takes effect if you are using Amazon S3 proper. It will _not_ have any effect with custom endpoints. DualStack support is deprecated by Amazon S3. We strongly advise you NOT to use it anymore.
### Alternate Date Format
By default, this library uses the standard date format `D, d M Y H:i:s O` which Amazon _incorrectly_ documents as "ISO 8601" (it's not, see the [ISO 8601 Wikipedia entry](https://en.wikipedia.org/wiki/ISO_8601) for reference). Most third party, Amazon S3-compatible services use the same and understand it just fine.
A minority of services don't understand the GMT offset at the end of the date format, and instead need the format `D, d M Y H:i:s T`. You can set a flag to enable this behaviour like so:
```php
$configuration->setAlternateDateHeaderFormat(true);
```
Caveat: Enabling this flag breaks compatibility with S3 proper.
### Using The HTTP Date Header Instead Of X-Amz-Date
Amazon documents that you should be using the standard HTTP `Date` header, and only resort to using the `X-Amz-Date` header when using the standard header is impossible, e.g. when creating pre-authorised (signed) URLs, or when your HTTP library does not let you set the standard header.
Unfortunately, some third party S3-compatible services such as Wasabi and ExoScale do _NOT_ support the standard `Date` header at all. Using it makes them falsely spit out a message about the signature being wrong. They are the reason why, by default, we are passing the request date and time using the `X-Amz-Date` header.
If you are using a third party service which for any reason does not understand the `X-Amz-Date` header you need to set a flag which forces the use of the standard `Date` header like so:
```php
$configuration->setUseHTTPDateHeader(true);
```