Download the PHP package matecat/simple-s3 without Composer

Simple S3 Client

[]() []()

Simple S3 Client is a simple wrapper of the official SDK PHP Client.

Basic Usage

To instantiate the Client do the following:

Please note that if you don't provide the credentials array, the Client will try to get values from the following environments variables on your system as the original S3Client:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN

If you instead want to authenticate assuming an IAM Role in another AWS Account do the following:

For further config details please refer to the official documentation:

Configuration for the AWS SDK for PHP Version 3

Methods

Here is the list of Client's public methods:

• clearBucket - clear a bucket from all files
• copyFolder - copy the items from a folder to another one
• copyItem - copy an item from a bucket to another one
• copyInBatch - copy in batch items from a bucket to another one
• createBucketIfItDoesNotExist . create a bucket if it does not exists
• createFolder . create an empty folder in a bucket if it does not exists
• deleteBucket - delete a bucket
• deleteBucketPolicy - delete the bucket policy
• deleteFolder - delete a folder
• deleteItem - delete an item
• downloadItem - download an item
• enableAcceleration - enable the acceleration mode for a bucket
• getBucketLifeCycle get the bucket lifecycle configuration
• getBucketPolicy get the bucket policy
• getBucketSize get the size (in Bytes) of files in a bucket
• getItem - get all informations for an item
• getItemsInABucket get an array of items in a bucket
• getItemsInAVersionedBucket get an array of items in a versioned bucket
• getCurrentItemVersion - get the latest version of an item
• getPublicItemLink - get the public link to download the item
• hasBucket - check if a bucket exists
• hasFolder - check if a folder exists
• hasItem - check if an item exists
• isBucketVersioned - check if bucket has versioned enabled
• openItem - get the content of an item
• restoreItem - try to restore an item from archive
• setBucketLifecycleConfiguration - set bucket lifecycle configuration
• setBucketPolicy - set the bucket policy
• setBucketVersioning - set the bucket versioning
• transfer - transfer content from/to buckets
• uploadItem - upload an item to a bucket from a file
• uploadItemFromBody - upload an item to a bucket from the body content

Naming validation for buckets and objects

Please refer to the official AWS policy:

• Bucket naming restrictions and limitations
• Object safe naming rules

The Client comes with two validators:

These two classes throws you an if the name provided is not compliant with the AWS rule conventions.

Validators are invoked in Client's , and methods.

Objects name escaping

Please read carefully the object safe naming rules.

Escaping object names is entirely up to you.

You can use the provided class, or inject in Client your own encoder if you prefer, but please note that it MUST implement

interface:

Filename trimming

As the Amazon official documentation reports, the filename max size on S3 is 1024 characters.

But you MUST be aware of filename max size of your operating system.

For example, if you run the application on a Linux system, this limit is 255 bytes, so you cannot download a file with a name which exceeds this value.

S3Client comes with a FilenameTrimmer helper class, which automatically trims the filenames. Default limit value is 255.

To override this limit, use setFilenameMaxSize method:

Bucket lifecycle

You can set the basic lifecycle for your bucket with method.

For further details please refer to the bucket lifecycle configuration official API documentation.

Bucket policy

You can set the bucket policy using method. Consider the following example:

You can grab bucket policy and delete it by using respectively and methods.

For further details please refer to the bucket policy official API documentation.

Bucket versioning

You can enable bucket versioning:

And now, when you use method, a tag will be added to keys:

For further details please refer to the bucket versioning official API documentation.

Restoring an item

You can use to send a restore an archived object. You can choose between three retrieval options:

• (lasts 5-12 hours)
• (default, lasts 1-5 minutes)
• (lasts 3-5 hours)

For further details please refer to the official documentation:

Restore an archived object

Caching

In order speed up data retrieval, you can inject a cache handler. Please note that the cache MUST implement . The client comes with a Redis implementation:

Now method will get the elements directly from cache. Please note that caching works ONLY if you provide a prefix to the method:

If you need to skip the cache you can add an extra parameter called exclude-cache:

Commands

If you have an application which uses Symfony Console, you have some commands available:

• Transfer files from/to a bucket.
• Clears a bucket.
• Creates a bucket.
• Deletes a bucket.
• Flush all data stored in cache.
• Get the cache statistics.
• Copy the items from a folder to another one.
• Copy an object from a bucket to another one.
• Deletes an object from a bucket.
• Download an object from a bucket.
• Upload an object into a bucket.

You can register the commands in your app, consider this example:

Logging

You can inject your logger to log every Client outcome call. Please note that your logger MUST be PSR-3 compliant:

Support

If you found an issue or had an idea please refer to this section.

Authors

• Mauro Cassani - github

License

This project is licensed under the MIT License - see the LICENSE.md file for details