PHPackages                             dtyq/cloudfile - 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. dtyq/cloudfile

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

dtyq/cloudfile
==============

Package description here.

v0.1.38(2w ago)010.1k↓51.8%Apache-2.0PHPPHP >=8.1

Since Apr 5Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/dtyq/cloudfile)[ Packagist](https://packagist.org/packages/dtyq/cloudfile)[ RSS](/packages/dtyq-cloudfile/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (42)Versions (40)Used By (0)

 cloud-file
============

[](#--cloud-file-)

 .

介绍
--

[](#介绍)

本 sdk 为文件服务 sdk 增强版，提供了更多的功能，更加易用。

内置阿里云、火山云、文件服务的简单调用，只需几行代码即可完成文件的上传、下载、删除等操作。

支持后端直传模式，获取临时凭证后，后端直接上传文件到云存储，减少服务器压力。

可替换的`FilesystemAdapter`配置，自定义更强。

抽离文件服务通用功能到包中，可不依赖文件服务即可使用。

支持的云
----

[](#支持的云)

- 文件服务代理的 阿里云、火山云
- 阿里云
- 火山云
- MinIO（兼容 S3 协议）

重要功能
----

[](#重要功能)

- 获取临时凭证
- 上传文件 - 通过临时凭证直传
- 复制文件
- 删除文件
- 批量获取可访问链接
- 获取文件元数据

注意事项
----

[](#注意事项)

如果要使用直连的阿里云、火山云，要先安装相应的FilesystemAdapter，如

```
"suggest": {
    "hyperf/logger": "Required to use the Hyperf.",
    "hyperf/di": "Required to use the Hyperf.",
    "hyperf/config": "Required to use the Hyperf.",
    "hyperf/cache": "Required to use the Hyperf.",
    "alibabacloud/sts": "^1.8",
    "aliyuncs/oss-sdk-php": "^2.7",
    "league/flysystem": "^2.0",
    "xxtime/flysystem-aliyun-oss": "^1.6",
    "volcengine/ve-tos-php-sdk": "^2.1",
    "volcengine/volc-sdk-php": "^1.0"
},

```

或者在 config 配置中，增加driver参数，即FilesystemAdapter，由于包之间依赖兼容性问题，可能会有bug，但目前使用文件服务服务的机会比较多，先不管这个了，有问题再改改

安装
--

[](#安装)

```
$ composer require dtyq/cloudfile -vvv
```

配置
--

[](#配置)

```
$configs = [
    'storages' => [
        // 文件服务配置示例
        'file_service_test' => [
            'adapter' => 'file_service',
            'config' => [
                // 文件服务地址
                'host' => 'xxx',
                // 文件服务的 platform
                'platform' => 'xxx',
                // 文件服务的 key
                'key' => 'xxx',
            ],
        ],
        // 阿里云配置示例
        'aliyun_test' => [
            'adapter' => 'aliyun',
            'config' => [
                'accessId' => 'xxx',
                'accessSecret' => 'xxx',
                'bucket' => 'xxx',
                'endpoint' => 'xxx',
                'role_arn' => 'xxx',
            ],
        ],
        // 火山云配置示例
        'tos_test' => [
            'adapter' => 'tos',
            'config' => [
                'region' => 'xxx',
                'endpoint' => 'xxx',
                'ak' => 'xxx',
                'sk' => 'xxx',
                'bucket' => 'xxx',
                'trn' => 'xxx',
            ],
        ],
        // MinIO 直连配置示例（底层复用 S3 协议实现）
        'minio_test' => [
            'adapter' => 'minio',
            'config' => [
                'region' => 'us-east-1',
                'endpoint' => 'http://localhost:9000', // MinIO 服务地址
                'accessKey' => 'xxx',
                'secretKey' => 'xxx',
                'bucket' => 'xxx',
                'use_path_style_endpoint' => true, // MinIO 必须为 true
                'version' => 'latest',
                'role_arn' => 'xxx', // 可选，用于 STS 临时凭证
            ],
        ],
    ],
];

$container = new SdkContainer([
    // sdk 基本配置
    'sdk_name' => 'easy_file_sdk',
    'exception_class' => CloudFileException::class,·
    // cloudfile 配置
    'cloudfile' => $configs,
]);

$cloudFile = new CloudFile($container);
```

文件服务特殊性
-------

[](#文件服务特殊性)

因为要请求文件服务，是需要动态 token 和 organization-code 的，这里需要放到 options 参数中，**所有**文件服务的请求，都需要带上，如下

```
$filesystem = $cloudFile->get('file_service_test');

$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
    'cache' => false, // 根据需要设置，建议 false，方便调试
];
```

使用
--

[](#使用)

### 获取临时凭证

[](#获取临时凭证)

```
$filesystem = $cloudFile->get('file_service_test');

$credentialPolicy = new CredentialPolicy([
    'sts' => false,
    'roleSessionName' => 'test',
]);
$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
$data = $filesystem->getUploadTemporaryCredential($credentialPolicy, $options);
```

### 上传文件 - 通过临时凭证直传

[](#上传文件---通过临时凭证直传)

上传完成后，记得查看`$uploadFile->getKey()`，来获取上传后的文件实际路径（因为文件服务会拼接 组织/应用 前缀）

```
$filesystem = $cloudFile->get('file_service_test');

$credentialPolicy = new CredentialPolicy([
    'sts' => false,
]);

$realPath = __DIR__ . '/../test.txt';

$uploadFile = new UploadFile($realPath, 'easy-file');
$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
$filesystem->uploadByCredential($uploadFile, $credentialPolicy, $options);
```

### 复制文件

[](#复制文件)

```
$filesystem = $cloudFile->get('file_service_test');

$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
// 复制文件成功后，要获取这个 path 结果才是真实地址，因为文件服务会有权限处理
$path = $filesystem->duplicate('easy-file/test.txt', 'easy-file/test-copy.txt', $options);
```

### 删除文件

[](#删除文件)

```
$filesystem = $cloudFile->get('file_service_test');

$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
$filesystem->destroy('easy-file/test.txt', $options);
```

### 批量获取可访问链接

[](#批量获取可访问链接)

> 请求文件服务时，不检测是否存在，直接返回链接

```
$filesystem = $cloudFile->get('file_service_test');

$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
$list = $filesystem->getLinks([
    'easy-file/file-service.txt',
    'easy-file/test.txt',
], [], 7200, $options);
```

### 获取文件元数据

[](#获取文件元数据)

```
$filesystem = $cloudFile->get('file_service_test');

$options = [
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
$list = $filesystem->getMetas([
    'easy-file/file-service.txt',
    'easy-file/test.txt'], $options);
```

Hyperf 快捷使用
-----------

[](#hyperf-快捷使用)

### 发布配置文件

[](#发布配置文件)

```
$ php bin/hyperf.php vendor:publish dtyq/cloudfile
```

### 使用

[](#使用-1)

```
// 这里可以在构造中注入 CloudFileFactory
$cloudFile = \Hyperf\Support\make(CloudFileFactory::class)->create();

$filesystem = $cloudFile->get('file_service');

$options = [
    // 这里的动态 token 需要自行传入
    'token' => 'xxx',
    'organization-code' => 'xxx',
];
$list = $filesystem->getLinks([
    'easy-file/file-service.txt',
    'easy-file/test.txt',
], [], 7200, $options);

$link = $list[0]->getUrl();
```

### Hyperf 中使用 MinIO

[](#hyperf-中使用-minio)

```
// 在 .env 中配置
MINIO_ENDPOINT=http://localhost:9000
MINIO_REGION=us-east-1
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key
MINIO_BUCKET=your-bucket

// 在代码中使用
$cloudFile = \Hyperf\Support\make(CloudFileFactory::class)->create();
$filesystem = $cloudFile->get('minio');

// 上传文件
$uploadFile = new UploadFile('/path/to/file.txt', 'my-folder');
$credentialPolicy = new CredentialPolicy(['sts' => false]);
$filesystem->uploadByCredential($uploadFile, $credentialPolicy);

// 获取文件链接
$links = $filesystem->getLinks(['my-folder/file.txt'], [], 3600);
```

MinIO 直连使用说明
------------

[](#minio-直连使用说明)

### 配置要点

[](#配置要点)

MinIO 是兼容 AWS S3 协议的对象存储，但对外配置仍使用 `adapter=minio`。使用时需要注意：

- `use_path_style_endpoint` 必须设置为 `true`
- `endpoint` 设置为 MinIO 服务地址（如 `http://localhost:9000`）
- `sts=false` 时，返回与 `file_service + platform=minio` 对齐的表单直传 credential，核心字段包括 `signature`、`policy`、`fields`
- `sts=true` 时，返回与 `file_service + platform=minio` 对齐的 STS credential，核心字段包括 `sts_token`、`access_key_id`、`access_key_secret`
- `uploadByCredential()` 固定走 `sts=false`
- `uploadByChunks()`、`appendUploadByCredential()`、`getPreSignedUrlByCredential()`、`listObjectsByCredential()` 等 SDK 能力固定走 `sts=true`

### 基本使用示例

[](#基本使用示例)

```
$filesystem = $cloudFile->get('minio_test');

// 获取临时凭证
$credentialPolicy = new CredentialPolicy([
    'sts' => false, // 返回 MinIO 表单直传 credential，字段语义与 file_service/minio 保持一致
    'roleSessionName' => 'test',
]);
$credential = $filesystem->getUploadTemporaryCredential($credentialPolicy);

// 上传文件
$realPath = __DIR__ . '/test.txt';
$uploadFile = new UploadFile($realPath, 'my-folder');
$filesystem->uploadByCredential($uploadFile, $credentialPolicy);

// 分片上传 / 预签名 URL 等 SDK 场景需要 STS 凭证
$stsPolicy = new CredentialPolicy([
    'sts' => true,
    'roleSessionName' => 'test',
]);
$stsCredential = $filesystem->getUploadTemporaryCredential($stsPolicy);

// 获取文件链接
$links = $filesystem->getLinks(['my-folder/test.txt'], [], 3600);
$downloadUrl = $links[0]->getUrl();

// 复制文件
$newPath = $filesystem->duplicate('my-folder/test.txt', 'my-folder/test-copy.txt');

// 删除文件
$filesystem->destroy('my-folder/test.txt');
```

### MinIO 与 AWS S3 的区别

[](#minio-与-aws-s3-的区别)

- MinIO 默认使用 path-style 访问（`http://endpoint/bucket/key`）
- AWS S3 默认使用 virtual-hosted-style 访问（`http://bucket.endpoint/key`）
- 通过设置 `use_path_style_endpoint => true` 可统一使用 path-style
- `cloudfile` 对外暴露的是 `minio` 适配器，内部复用的是 S3 协议实现
- 直连 `minio` 与 `file_service + platform=minio` 共享同一套 credential 语义，避免两套接入心智

```

```

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance93

Actively maintained with recent releases

Popularity25

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% 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 ~12 days

Recently: every ~29 days

Total

39

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1bdf9390d85a45dad64fe58584f55824c12a134a04e338d6259845683d9db137?d=identicon)[twosee](/maintainers/twosee)

---

Top Contributors

[![lihq1403](https://avatars.githubusercontent.com/u/25847339?v=4)](https://github.com/lihq1403 "lihq1403 (7 commits)")[![codingLee5](https://avatars.githubusercontent.com/u/112931300?v=4)](https://github.com/codingLee5 "codingLee5 (6 commits)")[![liaobw](https://avatars.githubusercontent.com/u/79210462?v=4)](https://github.com/liaobw "liaobw (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/dtyq-cloudfile/health.svg)

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

###  Alternatives

[laravel/framework

The Laravel Framework.

34.9k556.2M21.1k](/packages/laravel-framework)[leantime/leantime

Open source project management system for non-project managers. Simple like Trello, powerful like Jira. Built with neurodiversity in mind.

10.2k4.0k](/packages/leantime-leantime)[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k555.0M2.8k](/packages/aws-aws-sdk-php)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k293.8M1.1k](/packages/league-flysystem-aws-s3-v3)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k19](/packages/tempest-framework)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M651](/packages/shopware-core)

PHPackages © 2026

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