loongs / uploads

dev-main 2026-10-11 06:59 UTC

Requires

• php: ^8.4

Suggests

• aliyuncs/oss-sdk-php: Required for aliyun disk
• loongs/framework: Optional config() integration
• qcloud/cos-sdk-v5: Required for tencent disk
• qiniu/php-sdk: Required for qiniu disk

MIT

• storage
• upload
• oss
• qiniu
• swoole
• cos
• loongs

Published on Packagist.org on 2026-10-11 06:59 UTC

README

多渠道文件上传（loong-swoole / PHP 8.4+）：

渠道	driver	说明
本机服务器	local	支持外网 public_url 与内网 internal_url
阿里云 OSS	aliyun	自定义域名、私有读（签名 URL）
腾讯云 COS	tencent	同上
七牛 Kodo	qiniu	同上（domain 必填）

本包不内置云 SDK。使用对应渠道前请自行 composer require（见下文）。缺 SDK 时会抛出明确异常。

安装

composer require loongs/uploads:dev-main

按需安装云存储 SDK（不要三个都装，用哪个装哪个）：

# 阿里云 OSS
composer require aliyuncs/oss-sdk-php

# 腾讯云 COS
composer require qcloud/cos-sdk-v5

# 七牛
composer require qiniu/php-sdk

配置 config/uploads.php

将本仓库 config/uploads.php 复制到应用的 config/uploads.php，并用环境变量填充密钥。

启动时加载：

use Loongs\Uploads\Uploads;

Uploads::configure(require base_path('config/uploads.php'));
// 若使用 loongs/framework：Uploads::configure(config('uploads'));

主要环境变量：UPLOADS_DISK、UPLOADS_LOCAL_*、UPLOADS_ALIYUN_*、UPLOADS_TENCENT_*、UPLOADS_QINIU_*（详见示例配置文件）。

使用

use Loongs\Uploads\Uploads;

// 默认盘
Uploads::disk()->put('avatars/1.png', file_get_contents('/tmp/a.png'));
$url = Uploads::disk()->url('avatars/1.png');                 // 外网
$internal = Uploads::disk()->url('avatars/1.png', ['access' => 'internal']); // 本机内网

// 指定盘
Uploads::disk('aliyun')->putFile('docs/a.pdf', '/tmp/a.pdf');
$signed = Uploads::disk('aliyun')->temporaryUrl('docs/a.pdf', 600);

// helper
uploads()->put('x.txt', 'hi');
uploads('qiniu')->url('x.txt');

动态切换配置（不重启）

// 整表替换（会清空已解析的 disk 实例）
Uploads::configure(require base_path('config/uploads.php'));

// 只改默认盘
Uploads::setDefault('tencent');

// 运行时增改某一个 disk
Uploads::extend('aliyun', [
    'driver' => 'aliyun',
    'access_key' => '...',
    'secret_key' => '...',
    'bucket' => '...',
    'endpoint' => 'oss-cn-hangzhou.aliyuncs.com',
    'domain' => 'https://cdn.example.com',
    'private' => true,
]);

Uploads::flush(); // 仅丢弃缓存实例，保留配置

私有访问与自定义域名

• 云盘：private => true 时公开 url() 仍可能指向域名路径；请用 temporaryUrl($path, $seconds) 生成签名链接。
• domain：自定义 CDN / 绑定域名（七牛拼 URL 必须配置）。
• 本机盘：无签名；temporaryUrl 回退为 url()；用 access=public|internal 区分外网/内网基址。

License

MIT

Project config

On install into a Loongs app, missing config/*.php stubs from this package are copied into the project config/ directory (never overwritten). The app root should run bin/publish-loongs-configs.php from Composer post-autoload-dump (see loongs/uuims / loongs/loongs templates).