oss-flysystem

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 10 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OSS Flysystem

基于 [Alibaba Cloud OSS PHP SDK V2](https://github.com/aliyun/alibabacloud-oss-php-sdk-v2) 的 Flysystem 3 适配器。

## 要求

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

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

## 安装

```bash
composer require vergil-lai/oss-flysystem
```

## 使用

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

```php
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`：

```php
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`：

```php
$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，可直接使用适配器：

```php
$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`](https://github.com/vergil-lai/laravel-oss-filesystem)。它会通过 Composer 自动安装本包，并提供 `Storage::disk('oss')` 集成。

oss-flysystem

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README