szwtdl/storage

阿里云，腾讯云，七牛云，对象存储，支持laravel

v2.1.0 2026-04-11 23:57 UTC

Requires

• php: >=7.4
• ext-curl: *
• aliyuncs/oss-sdk-php: ^2.7
• qcloud/cos-sdk-v5: ^2.6
• qcloud_sts/qcloud-sts-sdk: ^3.0
• qiniu/php-sdk: ^7.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.10
• jetbrains/phpstorm-attributes: ^1.0
• mockery/mockery: ^1.4.4
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^9.5

Apache-2.0

• szwtdl

README

统一封装阿里云 OSS、腾讯云 COS、七牛云 Kodo，所有驱动都实现 Szwtdl\Storage\Service\IService。

安装

composer require szwtdl/storage

基础配置

use Szwtdl\Service\IService;
use Szwtdl\Storage;

$config = [
    'access_key' => 'your-access-key',
    'secret_key' => 'your-secret-key',
    'bucket' => 'demo-bucket',
    'endpoint' => 'oss-cn-qingdao',
    'options' => [
        'region' => 'oss-cn-qingdao',
        'domain' => 'https://cdn.example.com',
    ],
];

/** @var IService $storage */
$storage = Storage::driver('aliyun', $config);
// $storage = Storage::driver('tencent', $config);
// $storage = Storage::driver('qiniu', $config);

统一接口

interface IService
{
    public function getTemporaryCredentials(array $options = []): array;

    public function listBuckets(): array;

    public function createBucket(string $name, array $options = []): array;

    public function deleteBucket(string $name): array;

    public function listObj(array $options = []): array;

    public function upload(string $filePath, string $object): array;

    public function delete(string $object): array;

    public function download(string $object, string $filePath, array $options = []): array;
}

返回结构

存储桶列表 listBuckets

[
    [
        'name' => 'demo-bucket',
        'region' => 'oss-cn-qingdao',
        'class' => 'Standard',
        'domain' => 'https://cdn.example.com',
        'created_at' => '2026-04-12 10:00:00',
    ],
]

对象列表 listObj

[
    [
        'path' => 'demo/logo.png',
        'name' => 'logo.png',
        'size' => 12345,
        'type' => 'file',
        'etag' => 'etag-or-hash',
        'hash' => 'qiniu-hash-only',
        'url' => 'https://cdn.example.com/demo/logo.png',
        'last_modified' => '2026-04-12 10:00:00',
    ],
]

创建/删除存储桶

[
    'name' => 'demo-bucket',
    'status' => 'created', // 或 deleted
    'success' => true,
    'raw' => $sdkResponse,
]

上传结果 upload

[
    'path' => 'demo/logo.png',
    'name' => 'logo.png',
    'size' => 12345,
    'etag' => 'etag-or-hash',
    'hash' => 'qiniu-hash-only',
    'url' => 'https://cdn.example.com/demo/logo.png',
    'success' => true,
    'raw' => $sdkResponse,
]

删除结果 delete

[
    'path' => 'demo/logo.png',
    'success' => true,
    'raw' => $sdkResponse,
]

下载结果 download

[
    'path' => 'demo/logo.png',
    'save_as' => '/tmp/logo.png',
    'size' => 12345,
    'url' => 'https://cdn.example.com/demo/logo.png',
    'success' => true,
    'raw' => $sdkResponse,
]

临时凭证 getTemporaryCredentials

[
    'type' => 'sts', // 七牛为 upload_token
    'credentials' => [
        'access_key_id' => 'tmp-ak',
        'access_key_secret' => 'tmp-sk',
        'session_token' => 'token',
        'upload_token' => 'qiniu-upload-token',
    ],
    'expiration' => '2026-04-12T12:00:00Z',
    'expired_at' => 1760000000,
    'bucket' => 'demo-bucket',
    'region' => 'oss-cn-qingdao',
    'domain' => 'https://cdn.example.com',
    'success' => true,
    'raw' => $sdkResponse,
]

接口示例

1. 创建服务实例

use Szwtdl\Service\IService;
use Szwtdl\Storage;

/** @var IService $storage */
$storage = Storage::driver('aliyun', $config);

2. 获取存储桶列表

$buckets = $storage->listBuckets();

print_r($buckets);

2.1 获取临时凭证

阿里云 STS：

$result = $storage->getTemporaryCredentials([
    'role_arn' => 'acs:ram::1234567890123456:role/oss-sts-role',
    'role_session_name' => 'web-upload',
    'duration_seconds' => 3600,
]);

print_r($result);

腾讯云 STS：

$storage = Storage::driver('tencent', $config);

$result = $storage->getTemporaryCredentials([
    'duration_seconds' => 3600,
    'allow_prefix' => ['/*'],
    'allow_actions' => ['name/cos:*'],
]);

print_r($result);

七牛上传 Token：

$storage = Storage::driver('qiniu', $config);

$result = $storage->getTemporaryCredentials([
    'key' => 'demo/logo.png',
    'expires' => 3600,
]);

print_r($result);

如果你已经从业务侧拿到了临时凭证，也可以直接透传：

$result = $storage->getTemporaryCredentials([
    'credentials' => [
        'access_key_id' => 'tmp-ak',
        'access_key_secret' => 'tmp-sk',
        'session_token' => 'tmp-token',
    ],
    'expiration' => '2026-04-12T12:00:00Z',
    'expired_at' => 1760000000,
]);

3. 创建存储桶

$result = $storage->createBucket('demo-new-bucket', [
    'region' => 'oss-cn-qingdao',
]);

print_r($result);

4. 删除存储桶

$result = $storage->deleteBucket('demo-new-bucket');

print_r($result);

5. 获取对象列表

不传参数时，默认返回当前 bucket 下文件列表：

$list = $storage->listObj();

print_r($list);

按前缀筛选：

$list = $storage->listObj([
    'prefix' => 'demo/',
]);

print_r($list);

按目录层级列出：

$list = $storage->listObj([
    'prefix' => 'demo/',
    'delimiter' => '/',
]);

print_r($list);

如果配置了 options.domain，每一项都会包含完整访问地址：

$list = $storage->listObj();

echo $list[0]['url'] ?? null;

6. 上传文件

$result = $storage->upload('/absolute/path/logo.png', 'demo/logo.png');

echo $result['url'] ?? null;
print_r($result);

7. 删除文件

$result = $storage->delete('demo/logo.png');

var_dump($result['success']);

8. 下载文件

$result = $storage->download('demo/logo.png', '/tmp/logo.png');

echo $result['save_as'];
print_r($result);

Laravel 使用

发布配置：

php artisan vendor:publish --provider="Szwtdl\Storage\ServiceProvider"

使用容器：

/** @var \Szwtdl\Service\IService $storage */
$storage = app('storage');

$storage->upload('/absolute/path/logo.png', 'demo/logo.png');
$storage->listObj();
$storage->download('demo/logo.png', '/tmp/logo.png');
$storage->delete('demo/logo.png');