README

S3 Utilities库是一个综合工具包，专为与Amazon S3和S3兼容存储解决方案工作的开发者设计。此库包含广泛的特性，包括对S3参数的清洁、验证和序列化，确保符合AWS标准，并提高云存储操作的安全性和效率。

主要特性

全面清洁：通过删除或替换无效字符，确保存储桶名称、对象键、端点和其他参数符合S3标准。
强大验证：验证输入以确保它们符合AWS访问密钥、存储桶名称、对象键等特定标准，防止常见错误。
高级序列化：促进对象键的正确编码和解码，这对于处理S3对象路径中的特殊字符至关重要。
广泛兼容性：设计用于与AWS S3和各种S3兼容服务（如Linode、DigitalOcean Spaces和BackBlaze）无缝工作。
实用函数：提供验证和清洁的辅助函数，简化常见任务，简化开发。

通过利用S3 Utilities库，确保您的云存储交互得到优化、安全且合规。

最低要求

PHP： 7.4或更高版本

安装

要将S3 Utilities库集成到您的项目中，请使用Composer

composer require arraypress/s3-utilities

包括供应商库

将Composer自动加载器包含在您的项目中以访问库

require_once __DIR__ . '/vendor/autoload.php';

清洁类示例

Sanitize类提供了清洁Amazon S3操作各种参数的全面方法，确保符合AWS S3标准并提高数据安全性。

accessKey（清洁AWS访问密钥ID）

use ArrayPress\S3\Sanitize;

$accessKey = "AKIA1234EXAMPLE!@#$%";
$sanitizedAccessKey = Sanitize::accessKey($accessKey);
echo $sanitizedAccessKey; // Outputs: "AKIA1234EXAMPLE"

secretKey（清洁AWS秘密访问密钥）

$secretKey = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY%^&*";
$sanitizedSecretKey = Sanitize::secretKey($secretKey);
echo $sanitizedSecretKey; // Outputs: "wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY"

objectKey（清洁S3对象键）

$objectKey = "my_folder/my_file.txt*";
$sanitizedObjectKey = Sanitize::objectKey($objectKey);
echo $sanitizedObjectKey; // Outputs: "my_folder/my_file.txt"

bucket（清洁存储桶名称）

$bucketName = "My_Bucket-Name.123!";
$sanitizedBucketName = Sanitize::bucket($bucketName);
echo $sanitizedBucketName; // Outputs: "my-bucket-name.123"

region（清洁S3区域字符串）

$region = "us-west-1_extra";
$sanitizedRegion = Sanitize::region($region);
echo $sanitizedRegion; // Outputs: "us-west-1"

endpoint（清洁端点）

$endpoint = "https://my.endpoint.com/";
$sanitizedEndpoint = Sanitize::endpoint($endpoint);
echo $sanitizedEndpoint; // Outputs: "my.endpoint.com"

duration（清洁持续时间值）

$duration = -60;
$sanitizedDuration = Sanitize::duration($duration);
echo $sanitizedDuration; // Outputs: 60

extra_query_string（清洁额外查询字符串）

$extraQueryString = "param1=value1&param2=value2!";
$sanitizedQueryString = Sanitize::extra_query_string($extraQueryString);
echo $sanitizedQueryString; // Outputs: "param1=value1&param2=value2"

key（清洁通用键）

$key = "my_key-123!";
$sanitizedKey = Sanitize::key($key);
echo $sanitizedKey; // Outputs: "my_key-123"

bool（清洁布尔值）

$boolValue = "true";
$sanitizedBool = Sanitize::bool($boolValue);
echo $sanitizedBool ? 'true' : 'false'; // Outputs: true

html（清洁HTML字符串）

$htmlString = "<div>Some content</div>";
$sanitizedHtml = Sanitize::html($htmlString);
echo $sanitizedHtml; // Outputs: "&lt;div&gt;Some content&lt;/div&gt;"

url（清洁URL）

$url = "http://example.com/page?query=<unsafe string>";
$sanitizedUrl = Sanitize::url($url);
echo $sanitizedUrl; // Outputs: "http://example.com/page?query=%3Cunsafe%20string%3E"

验证类示例

Validate类提供了一系列方法，以确保您的Amazon S3操作使用正确格式和符合标准的参数。

accessKey（验证AWS访问密钥ID）

use ArrayPress\S3\Validate;

try {
    Validate::accessKey("AKIA1234EXAMPLE");
    echo "Access key is valid.";
} catch (InvalidArgumentException $e) {
    echo "Access key validation error: " . $e->getMessage();
}

secretKey（验证AWS秘密访问密钥）

try {
    Validate::secretKey("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");
    echo "Secret key is valid.";
} catch (InvalidArgumentException $e) {
    echo "Secret key validation error: " . $e->getMessage();
}

objectKey（验证S3对象键）

try {
    Validate::objectKey("my_folder/my_file.txt");
    echo "Object key is valid.";
} catch (InvalidArgumentException $e) {
    echo "Object key validation error: " . $e->getMessage();
}

bucket（验证存储桶名称）

try {
    Validate::bucket("my-bucket-name.123");
    echo "Bucket name is valid.";
} catch (InvalidArgumentException $e) {
    echo "Bucket name validation error: " . $e->getMessage();
}

region（验证S3区域字符串）

try {
    Validate::region( "us-west-1" );
    echo "Region is valid.";
} catch (InvalidArgumentException $e) {
    echo "Region validation error: " . $e->getMessage();
}

endpoint（验证端点）

try {
    Validate::endpoint( "my.endpoint.com" );
    echo "Endpoint is valid.";
} catch (InvalidArgumentException $e) {
    echo "Endpoint validation error: " . $e->getMessage();
}

duration（验证持续时间值）

try {
    Validate::duration( 60 );
    echo "Duration is valid.";
} catch (InvalidArgumentException $e) {
    echo "Duration validation error: " . $e->getMessage();
}

extraQueryString（验证额外查询字符串）

try {
    Validate::extraQueryString( "param1=value1&param2=value2" );
    echo "Extra query string is valid.";
} catch (InvalidArgumentException $e) {
    echo "Extra query string validation error: " . $e->getMessage();
}

序列化类示例

Serialization类促进S3对象键的编码和解码，以确保安全的存储路径。

encodeObjectName（编码S3对象名称）

将S3对象名称编码为URL安全表示对于正确处理特殊字符至关重要，尤其是在处理包含空格或保留字符的文件路径时。

use ArrayPress\S3\Serialization;

$objectName = "my folder/my file.txt";
$encodedObjectName = Serialization::encodeObjectName( $objectName );
echo $encodedObjectName; // Outputs: "my%20folder/my%20file.txt"

此方法确保空格被编码为%20，而斜杠（/）被保留，使字符串在URL中使用时安全，同时保留其作为路径分隔符的重要性。

decodeObjectName（解码URL编码的S3对象键）

解码与编码一样重要，尤其是在您需要根据URL编码路径检索和准确标识资源时。

$encodedKey = "my%20folder/my%20file.txt";
$decodedKey = Serialization::decodeObjectName( $encodedKey );
echo $decodedKey; // Outputs: "my folder/my file.txt"

此方法将URL编码的表示形式转换回其原始形式，允许正确识别和处理应用程序中的对象名称。

通过使用这些序列化方法，您可以在S3操作中确保对象名称始终以一致和安全的方式处理，最大限度地减少错误风险并提高数据管理实践。

S3操作辅助函数

辅助函数validate和sanitize分别提供了使用ArrayPress\S3命名空间中的Validate和Sanitize类进行验证和清理数据的简化接口。

验证辅助函数

validate函数检查给定值是否符合Validate类方法中定义的特定标准。如果验证成功，则返回true，否则返回false。

$isValid = validate( 'bucket', 'my-valid-bucket-name' );
if ( $isValid ) {
    echo "Bucket name is valid.";
} else {
    echo "Bucket name is invalid or method doesn't exist.";
}

此函数抽象了直接验证调用和异常处理的复杂性，使其更容易集成到验证流程中。

清理辅助函数

sanitize函数根据Sanitize类方法中指定的规则清理给定值。它直接返回清理后的值。

// Should output the sanitized version of the object key, e.g., "my folder/my file.txt"
$sanitizedValue = sanitize( 'objectKey', 'my folder/my file.txt*' );
echo $sanitizedValue;

如果Sanitize类中不存在指定的方法，则抛出InvalidArgumentException，指示实现错误。

注意：在检查方法是否存在之前直接使用sanitize可能会导致异常，如果方法名称不正确或不支持。

利用这些实用函数简化了确保与Amazon S3交互的数据格式正确和验证的过程，增强了S3操作的安全性和可靠性。

贡献

非常感谢对这个库的贡献。在GitHub上提出问题或提交错误修复或新功能的拉取请求。分享反馈和改进建议。

许可证：GPLv2或更高版本

此程序是免费软件；您可以在自由软件基金会发布的GNU通用公共许可证的条款下重新分发和/或修改它；许可证的第二版，或者（根据您的选择）任何更高版本。

此程序的分发是希望它将是有用的，但没有任何保证；甚至没有适销性或针对特定目的的隐含保证。有关详细信息，请参阅GNU通用公共许可证。

arraypress / s3-utilities

维护者

详细信息