README

S3路径解析库是一个针对管理Amazon S3和S3兼容存储路径的开发者的多功能工具包。它简化了解析、验证和清理S3路径的过程，符合AWS标准，并提高了云存储操作的健壮性。

主要特性

• 动态路径解析：从S3路径中提取存储桶和对象键，处理默认存储桶和自定义场景。
• 处理不允许的协议：防止S3路径中不支持的协议相关的错误。
• 文件扩展名验证：确保对象键具有有效的文件扩展名，可根据自定义列表进行设置。
• 配置灵活性：允许动态设置默认存储桶、允许的文件扩展名和不允许的协议。
• 增强安全性：为S3操作添加额外的验证层，确保路径安全且格式正确。

将S3路径解析器集成到您的项目中，以自信和精确地导航S3路径。

最低要求

• PHP：7.4或更高版本

安装

要将S3路径解析器集成到您的项目中，请使用Composer

composer require arraypress/s3-path-resolver

// Require the Composer autoloader.
require_once __DIR__ . '/vendor/autoload.php';

// Use the class and functions from the ArrayPress\S3 namespace.
use ArrayPress\S3\PathResolver;
use function ArrayPress\S3\EDD\is_s3_path;
use function ArrayPress\S3\WC\is_s3_path;

了解PathResolver中的路径解析

根据是否存在前导斜杠（/）和是否设置了默认存储桶，PathResolver类以不同的方式处理S3路径。以下是它的工作方式：

以/开头的路径

当路径以/开头时，紧随其后的部分被视为存储桶名称，其余部分被视为对象键。

// No default bucket set
$resolver = new PathResolver();
$pathInfo = $resolver->parsePath( '/mybucket/myfile.zip' );

echo "Bucket: " . $pathInfo->bucket; // Outputs: mybucket
echo "Object Key: " . $pathInfo->objectKey; // Outputs: myfile.zip`

无前导/且无默认存储桶的路径

如果路径不以/开头且未设置默认存储桶，则PathResolver无法解析存储桶，将导致失败。

$resolver = new PathResolver();
try {
    $pathInfo = $resolver->parsePath( 'myfile.zip' );
} catch ( Exception $e ) {
    echo "Error: " . $e->getMessage(); // Outputs: The provided path does not contain a valid bucket and object key.
}

设置默认存储桶

设置默认存储桶允许PathResolver解析未显式指定存储桶的路径。

$resolver = new PathResolver( 'default-bucket' );
$pathInfo = $resolver->parsePath( 'myfile.zip' );

echo "Bucket: " . $pathInfo->bucket; // Outputs: default-bucket
echo "Object Key: " . $pathInfo->objectKey; // Outputs: myfile.zip

特殊情况：默认存储桶和未指定存储桶名称的路径

如果您设置了默认存储桶，但也传递了未指定存储桶的路径（例如，files/mydog.zip），则PathResolver将默认存储桶应用于路径。

$resolver = new PathResolver( 'my-default-bucket' );
$pathInfo = $resolver->parsePath( 'files/mydog.zip' );

echo "Bucket: " . $pathInfo->bucket; // Outputs: my-default-bucket
echo "Object Key: " . $pathInfo->objectKey; // Outputs: files/mydog.zip

示例

1. 包含存储桶和对象键的有效路径

$resolver = new PathResolver();
$pathInfo = $resolver->parsePath( '/mybucket/myfile.zip' );

echo "Bucket: " . $pathInfo->bucket; // Outputs: mybucket
echo "Object Key: " . $pathInfo->objectKey; // Outputs: myfile.zip

2. 无前导斜杠且具有默认存储桶的路径

$resolver = new PathResolver( 'my-default-bucket' );
$pathInfo = $resolver->parsePath( 'myfile.zip' );

echo "Bucket: " . $pathInfo->bucket; // Outputs: my-default-bucket
echo "Object Key: " . $pathInfo->objectKey; // Outputs: myfile.zip

3. 路径中的无效协议

$resolver = new PathResolver();
try {
    $pathInfo = $resolver->parsePath( 'ftp://mybucket/myfile.zip' );
} catch (Exception $e) {
    echo "Error: " . $e->getMessage(); // Outputs: The provided path contains a disallowed protocol.
}

4. 无效的文件扩展名

$resolver = new PathResolver();
$resolver->setAllowedExtensions( ['zip', 'rar'] );
try {
    $pathInfo = $resolver->parsePath( '/mybucket/myfile.exe' );
} catch (Exception $e) {
    echo "Error: " . $e->getMessage(); // Outputs: The provided path has an invalid file extension.
}

5. 包含嵌套文件夹的路径

$resolver = new PathResolver();
$pathInfo = $resolver->parsePath( '/mybucket/folder1/folder2/myfile.zip' );

echo "Bucket: " . $pathInfo->bucket; // Outputs: mybucket
echo "Object Key: " . $pathInfo->objectKey; // Outputs: folder1/folder2/myfile.zip

6. 无前导斜杠且无默认存储桶的路径

$resolver = new PathResolver();
try {
    $pathInfo = $resolver->parsePath( 'myfile.zip' );
} catch ( Exception $e ) {
    echo "Error: " . $e->getMessage(); // Outputs: The provided path does not contain a valid bucket and object key.
}

Easy Digital Downloads和WooCommerce辅助函数

Easy Digital Downloads S3文件路径检查

// Check if an EDD download file is stored on S3.
$is_s3_file = is_s3_path( $download_id, $file_id, 'default-bucket', ['zip'], ['http://', 'https://' ], function ( $e ) {
    echo "Error: " . $e->getMessage();
});

echo $is_s3_file ? "File is on S3." : "File is not on S3.";

WooCommerce S3文件路径检查

// Verify if a WooCommerce product file is hosted on S3.
$is_s3_file = is_s3_path( $product_id, $download_id, 'default-bucket', ['pdf'], ['http://', 'https://' ], function ( $e ) {
    echo "Error: " . $e->getMessage();
});

echo $is_s3_file ? "Product file is on S3." : "Product file is not on S3.";

贡献

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

许可：GPLv2或更高版本

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

本程序的发布是希望它有用，但没有任何保证；甚至没有关于适销性或特定用途适用性的暗示保证。有关详细信息，请参阅GNU通用公共许可证。