{"id":18273458,"url":"https://github.com/arraypress/s3-utilities","last_synced_at":"2026-02-11T06:31:18.778Z","repository":{"id":205184337,"uuid":"713620247","full_name":"arraypress/s3-utilities","owner":"arraypress","description":"Offers utility methods for cleansing and validating input parameters associated with S3 operations.","archived":false,"fork":false,"pushed_at":"2024-11-06T21:02:58.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-03T19:35:38.556Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arraypress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-11-02T22:34:32.000Z","updated_at":"2024-11-06T21:03:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"1b34901e-8cc1-4283-b766-ed46f4a02cb8","html_url":"https://github.com/arraypress/s3-utilities","commit_stats":null,"previous_names":["arraypress/s3-sanitization","arraypress/s3-utilities"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/arraypress/s3-utilities","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fs3-utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fs3-utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fs3-utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fs3-utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arraypress","download_url":"https://codeload.github.com/arraypress/s3-utilities/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fs3-utilities/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29328261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"last_error":"SSL_read: 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":[],"created_at":"2024-11-05T12:06:32.822Z","updated_at":"2026-02-11T06:31:18.763Z","avatar_url":"https://github.com/arraypress.png","language":"PHP","readme":"# S3 Utilities Library\n\nThe S3 Utilities Library is a comprehensive toolkit designed for developers working with Amazon S3 and S3-compatible\nstorage solutions. This library encompasses a wide range of functionalities including sanitization, validation, and\nserialization of S3 parameters, ensuring adherence to AWS standards and enhancing the safety and efficiency of cloud\nstorage operations.\n\n**Key Features:**\n\n- **Comprehensive Sanitization:** Ensures that bucket names, object keys, endpoints, and other parameters conform to S3\n  standards by removing or replacing invalid characters.\n- **Robust Validation:** Validates inputs to ensure they meet specific criteria for AWS access keys, bucket names,\n  object keys, and more, preventing common errors.\n- **Advanced Serialization:** Facilitates the correct encoding and decoding of object keys, crucial for handling special\n  characters in S3 object paths.\n- **Wide Compatibility:** Designed to work seamlessly with AWS S3 and various S3-compatible services like Linode,\n  DigitalOcean Spaces, and BackBlaze.\n- **Utility Functions:** Provides helper functions for validation and sanitization, simplifying common tasks and\n  streamlining development.\n\nEnsure your cloud storage interactions are optimized, secure, and compliant by leveraging the S3 Utilities Library.\n\n## Minimum Requirements\n\n- **PHP:** 7.4 or later\n\n## Installation\n\nTo integrate the S3 Utilities Library into your project, use Composer:\n\n```bash\ncomposer require arraypress/s3-utilities\n```\n\n### Including the Vendor Library\n\nInclude the Composer autoloader in your project to access the library:\n\n```php\nrequire_once __DIR__ . '/vendor/autoload.php';\n```\n\n## Sanitize Class Examples\n\nThe `Sanitize` class provides comprehensive methods for sanitizing various parameters for Amazon S3 operations, ensuring\ncompliance with AWS S3 standards and enhancing data safety.\n\n### accessKey (Sanitizing AWS Access Key ID)\n\n```php\nuse ArrayPress\\S3\\Sanitize;\n\n$accessKey = \"AKIA1234EXAMPLE!@#$%\";\n$sanitizedAccessKey = Sanitize::accessKey($accessKey);\necho $sanitizedAccessKey; // Outputs: \"AKIA1234EXAMPLE\"\n```\n\n### secretKey (Sanitizing AWS Secret Access Key)\n\n```php\n$secretKey = \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY%^\u0026*\";\n$sanitizedSecretKey = Sanitize::secretKey($secretKey);\necho $sanitizedSecretKey; // Outputs: \"wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY\"\n```\n\n### objectKey (Sanitizing S3 Object Keys)\n\n```php\n$objectKey = \"my_folder/my_file.txt*\";\n$sanitizedObjectKey = Sanitize::objectKey($objectKey);\necho $sanitizedObjectKey; // Outputs: \"my_folder/my_file.txt\"\n```\n\n### bucket (Sanitizing Bucket Names)\n\n```php\n$bucketName = \"My_Bucket-Name.123!\";\n$sanitizedBucketName = Sanitize::bucket($bucketName);\necho $sanitizedBucketName; // Outputs: \"my-bucket-name.123\"\n```\n\n### region (Sanitizing S3 Region Strings)\n\n```php\n$region = \"us-west-1_extra\";\n$sanitizedRegion = Sanitize::region($region);\necho $sanitizedRegion; // Outputs: \"us-west-1\"\n```\n\n### endpoint (Sanitizing Endpoints)\n\n```php\n$endpoint = \"https://my.endpoint.com/\";\n$sanitizedEndpoint = Sanitize::endpoint($endpoint);\necho $sanitizedEndpoint; // Outputs: \"my.endpoint.com\"\n```\n\n### duration (Sanitizing Duration Values)\n\n```php\n$duration = -60;\n$sanitizedDuration = Sanitize::duration($duration);\necho $sanitizedDuration; // Outputs: 60\n```\n\n### extra_query_string (Sanitizing Extra Query Strings)\n\n```php\n$extraQueryString = \"param1=value1\u0026param2=value2!\";\n$sanitizedQueryString = Sanitize::extra_query_string($extraQueryString);\necho $sanitizedQueryString; // Outputs: \"param1=value1\u0026param2=value2\"\n```\n\n### key (Sanitizing Generic Keys)\n\n```php\n$key = \"my_key-123!\";\n$sanitizedKey = Sanitize::key($key);\necho $sanitizedKey; // Outputs: \"my_key-123\"\n```\n\n### bool (Sanitizing Boolean Values)\n\n```php\n$boolValue = \"true\";\n$sanitizedBool = Sanitize::bool($boolValue);\necho $sanitizedBool ? 'true' : 'false'; // Outputs: true\n```\n\n### html (Sanitizing HTML Strings)\n\n```php\n$htmlString = \"\u003cdiv\u003eSome content\u003c/div\u003e\";\n$sanitizedHtml = Sanitize::html($htmlString);\necho $sanitizedHtml; // Outputs: \"\u0026lt;div\u0026gt;Some content\u0026lt;/div\u0026gt;\"\n```\n\n### url (Sanitizing URLs)\n\n```php\n$url = \"http://example.com/page?query=\u003cunsafe string\u003e\";\n$sanitizedUrl = Sanitize::url($url);\necho $sanitizedUrl; // Outputs: \"http://example.com/page?query=%3Cunsafe%20string%3E\"\n```\n\n## Validate Class Examples\n\nThe `Validate` class offers a range of methods to ensure that your Amazon S3 operations use correctly formatted and\ncompliant parameters.\n\n### accessKey (Validating AWS Access Key ID)\n\n```php\nuse ArrayPress\\S3\\Validate;\n\ntry {\n    Validate::accessKey(\"AKIA1234EXAMPLE\");\n    echo \"Access key is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Access key validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### secretKey (Validating AWS Secret Access Key)\n\n```php\ntry {\n    Validate::secretKey(\"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\");\n    echo \"Secret key is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Secret key validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### objectKey (Validating S3 Object Keys)\n\n```php\ntry {\n    Validate::objectKey(\"my_folder/my_file.txt\");\n    echo \"Object key is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Object key validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### bucket (Validating Bucket Names)\n\n```php\ntry {\n    Validate::bucket(\"my-bucket-name.123\");\n    echo \"Bucket name is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Bucket name validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### region (Validating S3 Region Strings)\n\n```php\ntry {\n    Validate::region( \"us-west-1\" );\n    echo \"Region is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Region validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### endpoint (Validating Endpoints)\n\n```php\ntry {\n    Validate::endpoint( \"my.endpoint.com\" );\n    echo \"Endpoint is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Endpoint validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### duration (Validating Duration Values)\n\n```php\ntry {\n    Validate::duration( 60 );\n    echo \"Duration is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Duration validation error: \" . $e-\u003egetMessage();\n}\n```\n\n### extraQueryString (Validating Extra Query Strings)\n\n```php\ntry {\n    Validate::extraQueryString( \"param1=value1\u0026param2=value2\" );\n    echo \"Extra query string is valid.\";\n} catch (InvalidArgumentException $e) {\n    echo \"Extra query string validation error: \" . $e-\u003egetMessage();\n}\n```\n\n## Serialization Class Examples\n\nThe `Serialization` class facilitates the encoding and decoding of S3 object keys to ensure safe and compliant storage\npaths.\n\n### encodeObjectName (Encoding S3 Object Names)\n\nEncoding S3 object names into URL-safe representations is crucial for handling special characters correctly, especially\nwhen dealing with file paths that include spaces or reserved characters.\n\n```php\nuse ArrayPress\\S3\\Serialization;\n\n$objectName = \"my folder/my file.txt\";\n$encodedObjectName = Serialization::encodeObjectName( $objectName );\necho $encodedObjectName; // Outputs: \"my%20folder/my%20file.txt\"\n```\n\nThis method ensures that spaces are encoded as `%20` and slashes (`/`) are preserved, making the string safe for use in\nURLs while retaining its significance as a path delimiter.\n\n### decodeObjectName (Decoding URL-encoded S3 Object Keys)\n\nDecoding is as important as encoding, especially when you need to retrieve and accurately identify resources based on\nURL-encoded paths.\n\n```php\n$encodedKey = \"my%20folder/my%20file.txt\";\n$decodedKey = Serialization::decodeObjectName( $encodedKey );\necho $decodedKey; // Outputs: \"my folder/my file.txt\"\n```\n\nThis method converts URL-encoded representations back to their original form, allowing for the correct identification\nand handling of object names within your application.\n\nBy utilizing these serialization methods, you can ensure that object names are consistently and securely processed\nacross your S3 operations, minimizing the risk of errors and enhancing data management practices.\n\n## Helper Functions for S3 Operations\n\nThe helper functions `validate` and `sanitize` offer simplified interfaces for validating and sanitizing data respectively, by leveraging the `Validate` and `Sanitize` classes from the `ArrayPress\\S3` namespace.\n\n### Validate Helper Function\n\nThe `validate` function checks if a given value meets specific criteria defined in the `Validate` class methods. It returns `true` for successful validation or `false` otherwise.\n\n```php\n$isValid = validate( 'bucket', 'my-valid-bucket-name' );\nif ( $isValid ) {\n    echo \"Bucket name is valid.\";\n} else {\n    echo \"Bucket name is invalid or method doesn't exist.\";\n}\n```\n\nThis function abstracts the complexity of direct validation calls and exception handling, making it easier to integrate into validation flows.\n\n### Sanitize Helper Function\n\nThe `sanitize` function cleans a given value according to the rules specified in the `Sanitize` class methods. It directly returns the sanitized value.\n\n```php\n// Should output the sanitized version of the object key, e.g., \"my folder/my file.txt\"\n$sanitizedValue = sanitize( 'objectKey', 'my folder/my file.txt*' );\necho $sanitizedValue;\n```\n\nIn case the specified method does not exist within the `Sanitize` class, an `InvalidArgumentException` is thrown, indicating an implementation error.\n\nNote: Direct use of `sanitize` without checking for method existence might lead to exceptions if the method name is incorrect or not supported.\n\nUtilizing these utility functions streamlines the process of ensuring that data interacting with Amazon S3 is properly formatted and validated, enhancing the security and reliability of your S3 operations.\n\n## Contributions\n\nContributions to this library are highly appreciated. Raise issues on GitHub or submit pull requests for bug\nfixes or new features. Share feedback and suggestions for improvements.\n\n## License: GPLv2 or later\n\nThis program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public\nLicense as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied\nwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fs3-utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farraypress%2Fs3-utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fs3-utilities/lists"}