README

基于 Alibaba Cloud OSS PHP SDK V2 的 Flysystem 3 适配器。

要求

PHP 8.2+
阿里云 OSS bucket 的访问凭证与 region

OSS SDK V2 默认使用 V4 签名，因此必须配置 bucket 所在的 region。

安装

composer require vergil-lai/oss-flysystem

使用

本包直接接收 OSS SDK V2 原生 Client，不提供第二套客户端或配置格式：

use AlibabaCloud\Oss\V2\Client;
use AlibabaCloud\Oss\V2\Config as OssConfig;
use AlibabaCloud\Oss\V2\Credentials\StaticCredentialsProvider;
use League\Flysystem\Filesystem;
use VergilLai\OssFlysystem\OssFlysystemAdapter;

$config = OssConfig::loadDefault();
$config->setRegion(getenv('OSS_REGION') ?: 'cn-hangzhou');
$config->setCredentialsProvider(new StaticCredentialsProvider(
    (string) getenv('OSS_ACCESS_KEY_ID'),
    (string) getenv('OSS_ACCESS_KEY_SECRET'),
    getenv('OSS_SESSION_TOKEN') ?: null,
));

if ($endpoint = getenv('OSS_ENDPOINT')) {
    $config->setEndpoint($endpoint);
}

$client = new Client($config);
$adapter = new OssFlysystemAdapter(
    $client,
    (string) getenv('OSS_BUCKET'),
    baseUrl: getenv('OSS_URL') ?: null,
);
$filesystem = new Filesystem($adapter);

$filesystem->write('docs/readme.txt', 'Hello OSS');
$contents = $filesystem->read('docs/readme.txt');

endpoint 可选；未配置时由 SDK 根据 region 选择 endpoint。SDK V2 默认使用 V4 签名，如需 V1 可调用 $config->setSignatureVersion('v1')。代理、超时、重试和 endpoint 等参数均直接使用 SDK Config 的设置方法。

自定义凭证提供器和重试器

凭证提供器和重试器直接设置到 SDK Config：

use AlibabaCloud\Oss\V2\Credentials\EnvironmentVariableCredentialsProvider;
use AlibabaCloud\Oss\V2\Retry\StandardRetryer;

$config->setCredentialsProvider(new EnvironmentVariableCredentialsProvider());
$config->setRetryer(new StandardRetryer(maxAttempts: 5));

如果没有设置 retryer，SDK 会使用默认的 StandardRetryer。仅需调整最大重试次数时，可调用 $config->setRetryMaxAttempts(5)。

Root 与公开 URL

适配器的第三个参数是对象 key 的 root 前缀，第四个参数是公开 URL 的 baseUrl：

$adapter = new OssFlysystemAdapter(
    $client,
    (string) getenv('OSS_BUCKET'),
    'uploads',
    'https://cdn.example.com',
);

上例中 avatars/me.png 会存储为 uploads/avatars/me.png，$adapter->getUrl('avatars/me.png') 会返回以 https://cdn.example.com/uploads/ 开头的地址。

SDK Client 不公开其内部 endpoint 配置，因此本包不会从 Client 反向推断公开 URL。需要调用 publicUrl() 或 getUrl() 时必须传入 baseUrl；临时 URL 由 SDK presign() 生成，不受此限制。

支持的操作

写入、读取及流式读写
文件是否存在、文件大小、MIME 类型、最后修改时间和可见性
列出内容、复制、移动、删除文件和目录
checksum（使用 OSS ETag）
公开 URL、临时 GET URL 与临时 PUT 上传 URL

临时 URL 使用 SDK Config 设置的签名版本生成，默认为 OSS V4。除了 Flysystem 的 $filesystem->temporaryUrl() 外，如需临时上传 URL，可直接使用适配器：

$upload = $adapter->temporaryUploadUrl(
    'photo.jpg',
    new DateTimeImmutable('+10 minutes'),
    ['mimetype' => 'image/jpeg'],
);

// 使用 $upload['url'] 和 $upload['headers'] 发起 PUT 上传。

写入和临时上传支持 visibility、mimetype、cache_control、content_disposition、content_encoding、metadata、forbid_overwrite 与 storage_class 等常用选项。

Laravel

Laravel 项目请安装 vergil-lai/laravel-oss-filesystem。它会通过 Composer 自动安装本包，并提供 Storage::disk('oss') 集成。

vergil-lai / oss-flysystem

Maintainers

Package info

Statistics

Security

README

要求

安装

使用

自定义凭证提供器和重试器

Root 与公开 URL

支持的操作

Laravel