PHPackages                             szwtdl/storage - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. szwtdl/storage

ActiveLibrary[File & Storage](/categories/file-storage)

szwtdl/storage
==============

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

v2.1.0(2mo ago)0181Apache-2.0PHPPHP >=7.4CI passing

Since Sep 29Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/szwtdl/storage)[ Packagist](https://packagist.org/packages/szwtdl/storage)[ RSS](/packages/szwtdl-storage/feed)WikiDiscussions v2.0.0 Synced today

READMEChangelog (1)Dependencies (16)Versions (6)Used By (0)

对象存储
----

[](#对象存储)

统一封装阿里云 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`

[](#存储桶列表-listbuckets)

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

### 对象列表 `listObj`

[](#对象列表-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`

[](#上传结果-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`

[](#删除结果-delete)

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

### 下载结果 `download`

[](#下载结果-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`

[](#临时凭证-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. 创建服务实例

[](#1-创建服务实例)

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

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

### 2. 获取存储桶列表

[](#2-获取存储桶列表)

```
$buckets = $storage->listBuckets();

print_r($buckets);
```

### 2.1 获取临时凭证

[](#21-获取临时凭证)

阿里云 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. 创建存储桶

[](#3-创建存储桶)

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

print_r($result);
```

### 4. 删除存储桶

[](#4-删除存储桶)

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

print_r($result);
```

### 5. 获取对象列表

[](#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. 上传文件

[](#6-上传文件)

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

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

### 7. 删除文件

[](#7-删除文件)

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

var_dump($result['success']);
```

### 8. 下载文件

[](#8-下载文件)

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

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

Laravel 使用
----------

[](#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');
```

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance84

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~323 days

Total

5

Last Release

82d ago

Major Versions

v0.0.1 → v2.0.12026-04-11

### Community

Maintainers

![](https://www.gravatar.com/avatar/f32de7c4cbc21d8a95efcdcaec3e2cbffeffd80c9de0232c6a3a3dcd3aa3f55b?d=identicon)[szwtdl](/maintainers/szwtdl)

---

Top Contributors

[![szwtdl](https://avatars.githubusercontent.com/u/13212946?v=4)](https://github.com/szwtdl "szwtdl (8 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/szwtdl-storage/health.svg)

```
[![Health](https://phpackages.com/badges/szwtdl-storage/health.svg)](https://phpackages.com/packages/szwtdl-storage)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)