{"id":33999590,"url":"https://github.com/matecat/simple-s3","last_synced_at":"2026-04-08T19:31:11.037Z","repository":{"id":45293853,"uuid":"187001916","full_name":"matecat/simple-s3","owner":"matecat","description":"Simple S3 is a simple PHP client built on top of official AWS SDK","archived":false,"fork":false,"pushed_at":"2025-10-29T18:22:14.000Z","size":407,"stargazers_count":14,"open_issues_count":0,"forks_count":4,"subscribers_count":9,"default_branch":"master","last_synced_at":"2026-03-05T19:25:43.055Z","etag":null,"topics":["php-client","s3","s3-bucket","s3-client","s3-storage"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matecat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-05-16T10:00:28.000Z","updated_at":"2026-02-11T21:52:19.000Z","dependencies_parsed_at":"2023-12-15T03:43:50.212Z","dependency_job_id":"6e3ae8b0-b437-43c5-bf45-691bce092e67","html_url":"https://github.com/matecat/simple-s3","commit_stats":{"total_commits":161,"total_committers":4,"mean_commits":40.25,"dds":0.0496894409937888,"last_synced_commit":"85cd083832058c154479d0a322411b83ab4c75b3"},"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/matecat/simple-s3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matecat%2Fsimple-s3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matecat%2Fsimple-s3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matecat%2Fsimple-s3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matecat%2Fsimple-s3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matecat","download_url":"https://codeload.github.com/matecat/simple-s3/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matecat%2Fsimple-s3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31571599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php-client","s3","s3-bucket","s3-client","s3-storage"],"created_at":"2025-12-13T09:04:06.482Z","updated_at":"2026-04-08T19:31:11.010Z","avatar_url":"https://github.com/matecat.png","language":"PHP","readme":"# Simple S3 Client\n\n[![license](https://img.shields.io/github/license/matecat/simple-s3.svg)]()\n[![Packagist](https://img.shields.io/packagist/v/matecat/simple-s3.svg)]()\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/matecat/simple-s3/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/matecat/simple-s3/?branch=master)\n[![Code Coverage](https://scrutinizer-ci.com/g/matecat/simple-s3/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/matecat/simple-s3/?branch=master)\n\n**Simple S3 Client** is a simple wrapper of the official SDK PHP Client.\n\n## Basic Usage\n\nTo instantiate the Client do the following:\n\n```php\nuse Matecat\\SimpleS3\\Client;\n\n$s3Client = new Client([\n    'version' =\u003e 'latest',   // REQUIRED \n    'region' =\u003e 'us-west-2', // REQUIRED\n    'credentials' =\u003e [       // OPTIONAL \n        'key' =\u003e 'YOUR-ACCESS-KEY', \n        'secret' =\u003e 'YOUR-SECRET-KEY', \n        'token' =\u003e 'SESSION-TOKEN', \n    ]\n];\n```\n\nPlease note that if you don't provide the credentials array, the Client will try to [get values \nfrom the following environments variables on your system as the original S3Client](https://docs.aws.amazon.com/en_us/sdk-for-php/v3/developer-guide/guide_credentials_environment.html):\n\n* `AWS_ACCESS_KEY_ID`\n* `AWS_SECRET_ACCESS_KEY`\n* `AWS_SESSION_TOKEN`\n\nIf you instead want to authenticate assuming an IAM Role in another AWS Account do the following:\n\n```php\nuse Matecat\\SimpleS3\\Client;\n\n$s3Client = new Client([\n    'version' =\u003e 'latest',\n    'region' =\u003e 'us-west-2',\n    'iam' =\u003e [ \n        'arn' =\u003e 'arn:aws:iam::123456789012:role/xaccounts3acces', \n        'session' =\u003e 's3-access-example', \n    ]\n];\n```\n\nFor further config details please refer to the official documentation:\n\n[Configuration for the AWS SDK for PHP Version 3](https://docs.aws.amazon.com/en_us/sdk-for-php/v3/developer-guide/guide_configuration.html#credentials)\n\n## Methods\n\nHere is the list of Client's public methods:\n\n*   `clearBucket` - clear a bucket from all files\n*   `copyFolder` - copy the items from a folder to another one\n*   `copyItem` - copy an item from a bucket to another one\n*   `copyInBatch` - copy in batch items from a bucket to another one\n*   `createBucketIfItDoesNotExist` . create a bucket if it does not exists\n*   `createFolder` . create an empty folder in a bucket if it does not exists\n*   `deleteBucket` - delete a bucket\n*   `deleteBucketPolicy` - delete the bucket policy\n*   `deleteFolder` - delete a folder\n*   `deleteItem` - delete an item\n*   `downloadItem` - download an item\n*   `enableAcceleration` - enable the acceleration mode for a bucket\n*   `getBucketLifeCycle` get the bucket lifecycle configuration\n*   `getBucketPolicy` get the bucket policy\n*   `getBucketSize` get the size (in Bytes) of files in a bucket\n*   `getItem` - get all informations for an item\n*   `getItemsInABucket` get an array of items in a bucket\n*   `getItemsInAVersionedBucket` get an array of items in a versioned bucket\n*   `getCurrentItemVersion` - get the latest version of an item\n*   `getPublicItemLink` - get the public link to download the item\n*   `hasBucket` - check if a bucket exists\n*   `hasFolder` - check if a folder exists\n*   `hasItem` - check if an item exists\n*   `isBucketVersioned` - check if bucket has versioned enabled\n*   `openItem` - get the content of an item\n*   `restoreItem` - try to restore an item from archive\n*   `setBucketLifecycleConfiguration` - set bucket lifecycle configuration\n*   `setBucketPolicy` - set the bucket policy \n*   `setBucketVersioning` - set the bucket versioning \n*   `transfer` - transfer content from/to buckets\n*   `uploadItem` - upload an item to a bucket from a file\n*   `uploadItemFromBody` - upload an item to a bucket from the body content\n\n## Naming validation for buckets and objects\n\nPlease refer to the official AWS policy:\n\n*   [Bucket naming restrictions and limitations](https://docs.aws.amazon.com/en_us/AmazonS3/latest/dev/BucketRestrictions.html)\n*   [Object safe naming rules](https://docs.aws.amazon.com/en_us/AmazonS3/latest/dev/UsingMetadata.html)\n\nThe Client comes with two validators:\n \n*    ```S3BucketNameValidator``` \n*    ```S3ObjectSafeNameValidator``` \n \nThese two classes throws you an ```InvalidS3NameException``` if the name provided is not compliant with the AWS rule conventions. \n\nValidators are invoked in Client's ```createBucketIfItDoesNotExist```, ```uploadFileFromBody``` and ```uploadFile``` methods.\n\n## Objects name escaping\n\nPlease read carefully the [object safe naming rules](https://docs.aws.amazon.com/en_us/AmazonS3/latest/dev/UsingMetadata.html). \n\nEscaping object names is entirely up to you.\n\nYou can use the provided ```Matecat\\SimpleS3\\Components\\Encoders\\UrlEncoder``` class, or inject in Client your own encoder if you prefer, but please note that it MUST implement \n```Matecat\\SimpleS3\\Components\\Encoders\\SafeNameEncoderInterface``` \ninterface:\n\n```php\n...\n\nuse Matecat\\SimpleS3\\Components\\Encoders\\UrlEncoder;\n\n$encoder = new UrlEncoder();\n$s3Client-\u003eaddEncoder($encoder);\n```\n\n## Filename trimming\n\nAs the [Amazon official documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html) reports, the filename max size on S3 is **1024 characters**.\n\n__**But you MUST be aware of filename max size of your operating system.**__ \n\nFor 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.\n\nS3Client comes with a `FilenameTrimmer` helper class, which automatically trims the filenames. Default limit value is 255.\n\nTo override this limit, use `setFilenameMaxSize` method:\n\n```php\n...\n\n$client-\u003esetFilenameMaxSize(512);\n```\n\n## Bucket lifecycle\n\nYou can set the basic lifecycle for your bucket with ```setBucketLifecycleConfiguration``` method. \n\n```php\n...\n\n$s3Client-\u003esetBucketLifecycleConfiguration(['bucket' =\u003e $this-\u003ebucket, 'rules' =\u003e [...]]);\n```\n\nFor further details please refer to the [bucket lifecycle configuration official API documentation](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-lifecycle-configuration.html).\n\n## Bucket policy\n\nYou can set the bucket policy using ```setBucketPolicy``` method. Consider the following example:\n\n```php\n...\n\n$s3Client-\u003esetBucketPolicy([\n    'bucket' =\u003e 'mauretto78-bucket-test-policy', \n    'policy' =\u003e '{\n        \"Version\": \"2012-10-17\",\n        \"Id\": \"Versioning\",\n        \"Statement\": [\n            {\n                \"Effect\": \"Deny\",\n                \"Principal\": \"*\",\n                \"Action\": \"s3:GetBucketVersioning\",\n                \"Resource\": \"arn:aws:s3:::mauretto78-bucket-test-policy\"\n            }\n        ]\n    }'\n]);\n```\n\nYou can grab bucket policy and delete it by using respectively ```getBucketPolicy``` and ```deleteBucketPolicy``` methods.\n\nFor further details please refer to the [bucket policy official API documentation](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-policy.html).\n\n\n\n## Bucket versioning\n\nYou can enable bucket versioning:\n\n```php\n...\n\n$s3Client-\u003esetBucketVersioning(['bucket' =\u003e $this-\u003ebucket]);\n```\n\nAnd now, when you use ```getItemsInABucket``` method, a \u003cVERSION_ID\u003e tag will be added to keys:\n\n```php\n...\n\n// getItemsInABucket() will return something like this:\n$notHydrated = [\n    'key\u003cVERSION_ID=123456789\u003e',\n    'key\u003cVERSION_ID=234567890\u003e',\n    'key\u003cVERSION_ID=345678901\u003e',\n];\n\n$hydrated = [\n    'key\u003cVERSION_ID=123456789\u003e' =\u003e 'content',\n    'key\u003cVERSION_ID=234567890\u003e' =\u003e 'content',\n    'key\u003cVERSION_ID=345678901\u003e' =\u003e 'content',\n];\n```\n\nFor further details please refer to the [bucket versioning  official API documentation](https://docs.aws.amazon.com/en_us/AmazonS3/latest/API/RESTBucketPUTVersioningStatus.html).\n\n\n## Restoring an item\n\nYou can use ```restoreItem``` to send a restore an archived object. You can choose between three retrieval options:\n\n*    ```Bulk``` (lasts 5-12 hours)\n*    ```Expedited``` (default, lasts 1-5 minutes)\n*    ```Standard``` (lasts 3-5 hours)\n\nFor further details please refer to the official documentation:\n\n[Restore an archived object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html)\n\n## Caching\n\nIn order speed up data retrieval, you can inject a cache handler. Please note that the cache MUST implement ```Matecat\\SimpleS3\\Components\\Cache\\CacheInterface```.\nThe client comes with a Redis implementation:\n\n```php\n...\n\nuse Matecat\\SimpleS3\\Components\\Cache\\RedisCache;\n\n$redis = new Predis\\Client();\n$cacheAdapter = new RedisCache($redis);\n$s3Client-\u003eaddCache($cacheAdapter);\n```\n\nNow ```getItemsInABucket``` method will get the elements directly from cache. Please note that caching works ONLY if you provide a prefix to the method:\n\n```php\n...\n\n// this will get keys from cache\n$s3Client-\u003egetItemsInABucket([\n    'bucket' =\u003e 'your-bucket', \n    'prefix' =\u003e 'prefix/',\n    'hydrate' =\u003e true // false by default. If true is set the method returns an array of Aws\\ResultInterface \n]);\n\n// this will EVER get keys from S3\n$s3Client-\u003egetItemsInABucket('your-bucket');\n\n```\n\nIf you need to skip the cache you can add an extra parameter called `exclude-cache`:\n\n```php\n...\n\n// this will get keys from S3\n$s3Client-\u003egetItemsInABucket([\n    'bucket' =\u003e 'your-bucket', \n    'prefix' =\u003e 'prefix/',\n    'exclude-cache' =\u003e true \n]);\n\n```\n\n## Commands\n\nIf you have an application which uses [Symfony Console](https://github.com/symfony/console), you have some commands available:\n\n*  ```ss3:batch:transfer```  Transfer files from/to a bucket.\n*  ```ss3:bucket:clear```    Clears a bucket.\n*  ```ss3:bucket:create```   Creates a bucket.\n*  ```ss3:bucket:delete```   Deletes a bucket.\n*  ```ss3:cache:flush```     Flush all data stored in cache.\n*  ```ss3:cache:stats```     Get the cache statistics.\n*  ```ss3:folder:copy```     Copy the items from a folder to another one.\n*  ```ss3:item:copy```       Copy an object from a bucket to another one.\n*  ```ss3:item:delete```     Deletes an object from a bucket.\n*  ```ss3:item:download```   Download an object from a bucket.\n*  ```ss3:item:upload```     Upload an object into a bucket.\n\nYou can register the commands in your app, consider this example:\n\n```php\n#!/usr/bin/env php\n\u003c?php\nset_time_limit(0);\n\nrequire __DIR__.'/../vendor/autoload.php';\n\n$config = parse_ini_file(__DIR__.'/../config/credentials.ini');\n$s3Client = new \\Matecat\\SimpleS3\\Client(\n    [\n        'version' =\u003e $config['VERSION'],\n        'region' =\u003e $config['REGION'],\n        'credentials' =\u003e [\n            'key' =\u003e $config['ACCESS_KEY_ID'],\n            'secret' =\u003e $config['SECRET_KEY']\n        ]\n    ]\n);\n\n$redis = new Predis\\Client();\n$cacheAdapter = new \\Matecat\\SimpleS3\\Components\\Cache\\RedisCache($redis);\n$s3Client-\u003eaddCache($cacheAdapter);\n\n// create symfony console app\n$app = new \\Symfony\\Component\\Console\\Application('Simple S3', 'console tool');\n\n// add commands here\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\BatchTransferCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\BucketClearCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\BucketCreateCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\BucketDeleteCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\CacheFlushCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\CacheStatsCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\FolderCopyCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\ItemCopyCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\ItemDeleteCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\ItemDownloadCommand($s3Client));\n$app-\u003eadd(new \\Matecat\\SimpleS3\\Console\\ItemUploadCommand($s3Client));\n\n$app-\u003erun();\n```\n\n## Logging\n\nYou can inject your logger to log every Client outcome call. Please note that your logger MUST be PSR-3 compliant:\n\n```php\n...\n\n// $logger MUST implement Psr\\Log\\LoggerInterface\n\n$s3Client-\u003eaddLogger($logger); \n```\n\n## Support\n\nIf you found an issue or had an idea please refer [to this section](https://github.com/mauretto78/simple-s3/issues).\n\n## Authors\n\n* **Mauro Cassani** - [github](https://github.com/mauretto78)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatecat%2Fsimple-s3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatecat%2Fsimple-s3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatecat%2Fsimple-s3/lists"}