matecat/simple-s3

简单 S3 客户端

维护者

详细信息

github.com/matecat/simple-s3

主页

源代码

问题

安装次数: 6,946

依赖项: 0

建议者: 0

安全: 0

星标: 12

关注者: 11

分支: 4

开放问题: 1

v1.5.12 2024-09-25 08:24 UTC

Requires

Requires (Dev)

MIT e0031c7d841b7d58427c603a726b1495d6e8b5c2

phps3sdkaws

This package is auto-updated.

Last update: 2024-09-25 08:26:25 UTC

README

license Packagist Scrutinizer Code Quality Code Coverage

简单 S3 客户端 是官方 SDK PHP 客户端的简单封装。

基本用法

要实例化客户端，请执行以下操作

use Matecat\SimpleS3\Client;

$s3Client = new Client([
    'version' => 'latest',   // REQUIRED 
    'region' => 'us-west-2', // REQUIRED
    'credentials' => [       // OPTIONAL 
        'key' => 'YOUR-ACCESS-KEY', 
        'secret' => 'YOUR-SECRET-KEY', 
        'token' => 'SESSION-TOKEN', 
    ]
];

请注意，如果您不提供凭证数组，客户端将尝试从系统中的以下环境变量获取值，就像原始 S3Client 一样

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_SESSION_TOKEN

如果您想假设另一个 AWS 账户中的 IAM 角色进行认证，请执行以下操作

use Matecat\SimpleS3\Client;

$s3Client = new Client([
    'version' => 'latest',
    'region' => 'us-west-2',
    'iam' => [ 
        'arn' => 'arn:aws:iam::123456789012:role/xaccounts3acces', 
        'session' => 's3-access-example', 
    ]
];

有关进一步配置详细信息，请参阅官方文档

AWS SDK for PHP 版本 3 的配置

方法

以下是客户端的公共方法列表

  • clearBucket - 清除存储桶中的所有文件
  • copyFolder - 从一个文件夹复制项目到另一个文件夹
  • copyItem - 从一个存储桶复制项目到另一个存储桶
  • copyInBatch - 批量从存储桶复制项目到另一个存储桶
  • createBucketIfItDoesNotExist - 如果不存在，则创建一个存储桶
  • createFolder - 如果不存在，则在存储桶中创建一个空文件夹
  • deleteBucket - 删除一个存储桶
  • deleteBucketPolicy - 删除存储桶策略
  • deleteFolder - 删除一个文件夹
  • deleteItem - 删除一个项目
  • downloadItem - 下载一个项目
  • enableAcceleration - 启用存储桶的加速模式
  • getBucketLifeCycle 获取存储桶的生命周期配置
  • getBucketPolicy 获取存储桶策略
  • getBucketSize 获取存储桶中文件的字节大小
  • getItem - 获取一个项目的所有信息
  • getItemsInABucket 获取存储桶中的项目数组
  • getItemsInAVersionedBucket 获取版本化存储桶中的项目数组
  • getCurrentItemVersion - 获取项目的最新版本
  • getPublicItemLink - 获取下载项目的公共链接
  • hasBucket - 检查存储桶是否存在
  • hasFolder - 检查文件夹是否存在
  • hasItem - 检查项目是否存在
  • isBucketVersioned - 检查存储桶是否启用了版本控制
  • openItem - 获取项目的内文
  • restoreItem - 尝试从存档中恢复项目
  • setBucketLifecycleConfiguration - 设置存储桶生命周期配置
  • setBucketPolicy - 设置存储桶策略
  • setBucketVersioning - 设置存储桶版本控制
  • transfer - 在存储桶之间传输内容
  • uploadItem - 从文件上传项目到存储桶
  • uploadItemFromBody - 从内容体上传项目到存储桶

存储桶和对象的命名验证

请参阅官方 AWS 策略

客户端包含两个验证器

  • S3BucketNameValidator
  • S3ObjectSafeNameValidator

这两个类如果提供的名称不符合 AWS 规则约定，则会抛出 InvalidS3NameException。

验证器在客户端的 createBucketIfItDoesNotExist、uploadFileFromBody 和 uploadFile 方法中被调用。

对象名称转义

请仔细阅读对象安全命名规则。

对象名称的转义完全由您决定。

您可以使用提供的 Matecat\SimpleS3\Components\Encoders\UrlEncoder 类，或者如果您愿意，可以在客户端注入您自己的编码器，但请注意，它必须实现 Matecat\SimpleS3\Components\Encoders\SafeNameEncoderInterface 接口。

...

use Matecat\SimpleS3\Components\Encoders\UrlEncoder;

$encoder = new UrlEncoder();
$s3Client->addEncoder($encoder);

文件名修剪

如Amazon官方文档所述，S3上的文件名最大长度为 1024 个字符。

但您必须了解操作系统的文件名最大长度。

例如，如果您在Linux系统上运行应用程序，此限制为 255 字节，因此您不能下载名称超过此值的文件。

S3Client附带一个名为FilenameTrimmer的辅助类，它可以自动修剪文件名。默认限制值为255。

要覆盖此限制，请使用setFilenameMaxSize方法。

...

$client->setFilenameMaxSize(512);

存储桶生命周期

您可以使用setBucketLifecycleConfiguration方法设置存储桶的基本生命周期。

...

$s3Client->setBucketLifecycleConfiguration(['bucket' => $this->bucket, 'rules' => [...]]);

有关更多详细信息，请参阅存储桶生命周期配置官方API文档。

存储桶策略

您可以使用setBucketPolicy方法设置存储桶策略。以下是一个示例

...

$s3Client->setBucketPolicy([
    'bucket' => 'mauretto78-bucket-test-policy', 
    'policy' => '{
        "Version": "2012-10-17",
        "Id": "Versioning",
        "Statement": [
            {
                "Effect": "Deny",
                "Principal": "*",
                "Action": "s3:GetBucketVersioning",
                "Resource": "arn:aws:s3:::mauretto78-bucket-test-policy"
            }
        ]
    }'
]);

您可以使用分别的getBucketPolicy和deleteBucketPolicy方法获取和删除存储桶策略。

有关更多详细信息，请参阅存储桶策略官方API文档。

存储桶版本控制

您可以启用存储桶版本控制

...

$s3Client->setBucketVersioning(['bucket' => $this->bucket]);

现在，当您使用getItemsInABucket方法时，将在键中添加一个 <VERSION_ID> 标签

...

// getItemsInABucket() will return something like this:
$notHydrated = [
    'key<VERSION_ID=123456789>',
    'key<VERSION_ID=234567890>',
    'key<VERSION_ID=345678901>',
];

$hydrated = [
    'key<VERSION_ID=123456789>' => 'content',
    'key<VERSION_ID=234567890>' => 'content',
    'key<VERSION_ID=345678901>' => 'content',
];

有关更多详细信息，请参阅存储桶版本控制官方API文档。

恢复项

您可以使用restoreItem发送恢复存档对象。您可以选择三种检索选项

  • 批量（持续5-12小时）
  • 加急（默认，持续1-5分钟）
  • 标准（持续3-5小时）

有关更多详细信息，请参阅官方文档

恢复存档对象

缓存

为了加快数据检索，您可以注入一个缓存处理程序。请注意，缓存必须实现Matecat\SimpleS3\Components\Cache\CacheInterface。客户端附带一个Redis实现

...

use Matecat\SimpleS3\Components\Cache\RedisCache;

$redis = new Predis\Client();
$cacheAdapter = new RedisCache($redis);
$s3Client->addCache($cacheAdapter);

现在，getItemsInABucket方法将直接从缓存获取元素。请注意，只有当您向方法提供前缀时，缓存才会起作用。

...

// this will get keys from cache
$s3Client->getItemsInABucket([
    'bucket' => 'your-bucket', 
    'prefix' => 'prefix/',
    'hydrate' => true // false by default. If true is set the method returns an array of Aws\ResultInterface 
]);

// this will EVER get keys from S3
$s3Client->getItemsInABucket('your-bucket');

如果您需要跳过缓存，您可以添加一个名为exclude-cache的额外参数。

...

// this will get keys from S3
$s3Client->getItemsInABucket([
    'bucket' => 'your-bucket', 
    'prefix' => 'prefix/',
    'exclude-cache' => true 
]);

命令

如果您有一个使用Symfony Console的应用程序，您有一些可用的命令

  • ss3:batch:transfer 在存储桶之间传输文件。
  • ss3:bucket:clear 清除存储桶。
  • ss3:bucket:create 创建存储桶。
  • ss3:bucket:delete 删除存储桶。
  • ss3:cache:flush 清除存储在缓存中的所有数据。
  • ss3:cache:stats 获取缓存统计信息。
  • ss3:folder:copy 将项目从文件夹复制到另一个文件夹。
  • ss3:item:copy 从存储桶复制一个对象到另一个存储桶。
  • ss3:item:delete 从存储桶删除一个对象。
  • ss3:item:download 从存储桶下载一个对象。
  • ss3:item:upload 将对象上传到存储桶。

您可以在应用程序中注册这些命令，以下是一个示例

#!/usr/bin/env php
<?php
set_time_limit(0);

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

$config = parse_ini_file(__DIR__.'/../config/credentials.ini');
$s3Client = new \Matecat\SimpleS3\Client(
    [
        'version' => $config['VERSION'],
        'region' => $config['REGION'],
        'credentials' => [
            'key' => $config['ACCESS_KEY_ID'],
            'secret' => $config['SECRET_KEY']
        ]
    ]
);

$redis = new Predis\Client();
$cacheAdapter = new \Matecat\SimpleS3\Components\Cache\RedisCache($redis);
$s3Client->addCache($cacheAdapter);

// create symfony console app
$app = new \Symfony\Component\Console\Application('Simple S3', 'console tool');

// add commands here
$app->add(new \Matecat\SimpleS3\Console\BatchTransferCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\BucketClearCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\BucketCreateCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\BucketDeleteCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\CacheFlushCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\CacheStatsCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\FolderCopyCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\ItemCopyCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\ItemDeleteCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\ItemDownloadCommand($s3Client));
$app->add(new \Matecat\SimpleS3\Console\ItemUploadCommand($s3Client));

$app->run();

日志记录

您可以将日志记录器注入到日志每个客户端结果调用。请注意，您的日志记录器必须遵循PSR-3规范。

...

// $logger MUST implement Psr\Log\LoggerInterface

$s3Client->addLogger($logger);

支持

如果您发现了问题或有任何想法，请参考本部分。

作者

许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE.md文件。