README

S3 Signer Library 简化了生成Amazon S3对象的预签名URL，方便安全、临时的访问，而无需直接暴露AWS凭证。此库对于需要安全、限时访问S3对象的应用程序至关重要，例如共享私有文件或提供临时下载链接。

主要功能

• 支持路径样式和虚拟主机样式URL：提供灵活的URL格式，以适应各种存储桶命名约定和需求。
• 可配置的URL有效期：自定义预签名URL的有效期限，从几分钟到几天。
• 附加查询参数：将额外的查询参数附加到生成的URL，以实现对访问的精细控制。
• 兼容S3和相关服务：不仅与AWS S3兼容，还与S3兼容的服务（如Cloudflare R2）兼容，适用于不同的存储解决方案。

安装

使用Composer将S3 Signer Library安装到您的项目中

composer require arraypress/s3-signer

快速入门

安装后，在您的PHP脚本中包含Composer自动加载器

require 'vendor/autoload.php';

使用您的S3凭证和端点创建一个Signer类的实例

use ArrayPress\S3\Signer\Signer;

$accessKey = 'your-access-key-id';
$secretKey = 'your-secret-access-key';
$endpoint = '{account_id}.r2.cloudflarestorage.com'; // Or your S3-compatible service endpoint
$region = 'auto';

$signer = new Signer( $accessKey, $secretKey, $endpoint, $region );

为S3对象生成预签名URL

$bucket = 'your-bucket-name';
$objectKey = 'mydownload.zip';
$duration = 60; // URL is valid for 60 minutes

$signedUrl = $signer->getObjectUrl( $bucket, $objectKey, $duration );

echo "Pre-Signed URL: $signedUrl\n";

高级用法

您可以通过使用可用的setter方法进一步自定义Signer类的行为。这些方法允许您动态设置Signer实例的属性，以满足您对S3或S3兼容服务操作的特定要求。

设置访问密钥ID

设置AWS S3访问密钥ID以验证您的请求。

$signer->setAccessKey( 'your-access-key-id' );

此方法验证并设置用于S3操作访问密钥ID，确保其符合AWS要求的格式。

设置秘密访问密钥

设置与您的访问密钥ID对应的AWS S3秘密访问密钥。

$signer->setSecretKey( 'your-secret-access-key' );

秘密访问密钥对于安全地签名请求至关重要。此方法还验证密钥以确保其符合AWS标准。

设置端点

指定您的S3或S3兼容服务的端点URL。

$signer->setEndpoint( 's3.amazonaws.com' );

使用此方法设置S3请求发送到的端点。它经过验证以确保适当的URL格式。

设置区域

定义您的S3存储桶所在的AWS区域。

$signer->setRegion( 'us-west-2' );

正确设置区域对于构建签名URL和确保其路由到正确的数据中心至关重要。

设置路径样式

在路径样式和虚拟主机样式URL之间切换。

$signer->setPathStyle( true ); // Use path-style URLs

随着AWS转向使用虚拟主机样式URL，路径样式URL正在逐渐淘汰，但在某些情况下或与特定S3兼容服务一起使用时可能仍然需要或首选。

设置附加查询字符串

将额外的查询参数附加到您的预签名URL。

$signer->setExtraQueryString( 'versionId=1234' );

此方法允许您添加额外的查询字符串参数，提供版本控制、访问管理或其他特定于服务的功能的灵活性。

示例用法

以下是您如何使用这些方法一起配置Signer实例以生成预签名URL的示例

$signer = new Signer( 'access-key-id', 'secret-access-key', 's3.amazonaws.com' );
$signer->setRegion( 'us-west-2' ); 
$signer->setPathStyle( false ); // Use virtual-hosted-style URLs
$signer->setExtraQueryString( 'response-content-disposition=attachment' );

$signedUrl = $signer->getObjectUrl( 'your-bucket-name', 'path/to/your/object', 60 );
echo "Pre-Signed URL: $signedUrl\n"; 

在此示例中，我们已配置Signer生成一个对象的有效期为60分钟的虚拟主机样式URL，并附加一个额外的查询参数，指示S3在访问时提示用户下载对象。

支持的提供商

此库支持为AWS S3和其他遵循SigV4签名过程的S3兼容存储解决方案生成预签名URL。支持的提供商包括

• AWS S3: 原始且最全面的云存储服务。
• Cloudflare R2: 提供与S3 API的兼容性以及具有竞争力的定价。
• DigitalOcean Spaces: 提供简单、可扩展的存储，支持S3兼容的API。
• Linode Object Storage: 提供用于存储和访问数据的S3兼容存储。
• 更多选择：任何使用SigV4的S3兼容服务都可以与这个库一起工作。

使用 getObjectUrl 辅助函数

您还可以使用 getObjectUrl 辅助函数以更直接的方式生成预签名URL。

$signedUrl = getObjectUrl(
    'your-access-key-id',
    'your-secret-access-key',
    's3.amazonaws.com',
    'your-bucket-name',
    'path/to/your/object',
    60, // Duration in minutes
    '', // Extra query string
    'us-west-2', // Region
    true // Use path style
);

echo "Pre-Signed URL using helper function: $signedUrl\n";

贡献

我们非常欢迎对这个库的贡献。在GitHub上提出问题或提交补丁请求以修复错误或添加新功能。分享改进的反馈和建议。

许可证：GPLv2或更高版本

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

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