README

This is a Flysystem adapter for the Tencent Cloud COS (Cloud Object Storage).

Requirements

PHP >= 8.2
League Flysystem ^2.0 || ^3.0
qcloud/cos-sdk-v5 ^2.6

Installation

composer require larva/flysystem-cos -vv

Usage

基础用法

<?php

use Larva\Flysystem\Tencent\TencentCOSAdapter;
use League\Flysystem\Filesystem;
use Qcloud\Cos\Client;

// 创建 COS 客户端
$client = new Client([
    'region'      => env('COS_REGION', 'ap-guangzhou'),
    'credentials' => [
        'secretId'  => env('COS_SECRET_ID'),
        'secretKey' => env('COS_SECRET_KEY'),
    ],
]);

// 创建适配器
$adapter = new TencentCOSAdapter(
    $client,
    bucket: env('COS_BUCKET'),       // 存储桶名称
    prefix: '',                       // 路径前缀，可选
);

// 创建文件系统实例
$filesystem = new Filesystem($adapter);

文件操作

// 写入文件
$filesystem->write('path/to/file.txt', 'contents');

// 写入文件（流）
$stream = fopen('/path/to/local/file.txt', 'r');
$filesystem->writeStream('path/to/file.txt', $stream);
fclose($stream);

// 读取文件
$contents = $filesystem->read('path/to/file.txt');

// 读取文件（流）
$stream = $filesystem->readStream('path/to/file.txt');
fclose($stream);

// 检查文件是否存在
$exists = $filesystem->fileExists('path/to/file.txt');

// 删除文件
$filesystem->delete('path/to/file.txt');

// 复制文件
$filesystem->copy('path/from.txt', 'path/to.txt');

// 移动文件
$filesystem->move('path/from.txt', 'path/to.txt');

目录操作

// 创建目录
$filesystem->createDirectory('path/to/dir');

// 检查目录是否存在
$filesystem->directoryExists('path/to/dir');

// 删除目录（递归删除目录下所有对象）
$filesystem->deleteDirectory('path/to/dir');

// 列出目录内容
foreach ($filesystem->listContents('path/to/dir', true) as $item) {
    echo $item->path() . PHP_EOL;
}

可见性设置

use League\Flysystem\Visibility;

// 写入时指定可见性
$filesystem->write('public/file.txt', 'contents', [
    'visibility' => Visibility::PUBLIC,
]);

// 设置文件可见性
$filesystem->setVisibility('path/to/file.txt', Visibility::PUBLIC);

// 获取文件可见性
$visibility = $filesystem->visibility('path/to/file.txt');

支持的可见性映射：

Flysystem 可见性	COS ACL
`Visibility::PUBLIC`	`public-read`
`Visibility::PRIVATE`	`private`

元数据获取

// 获取文件 MIME 类型
$mimeType = $filesystem->mimeType('path/to/file.txt')->mimeType();

// 获取文件大小
$fileSize = $filesystem->fileSize('path/to/file.txt')->fileSize();

// 获取最后修改时间
$lastModified = $filesystem->lastModified('path/to/file.txt')->lastModified();

高级配置

构造方法支持传入默认选项和自定义可见性转换器：

use Larva\Flysystem\Tencent\TencentCOSAdapter;
use Larva\Flysystem\Tencent\PortableVisibilityConverter;
use League\Flysystem\Visibility;

$adapter = new TencentCOSAdapter(
    $client,
    bucket: 'your-bucket',
    prefix: 'uploads/',
    visibility: new PortableVisibilityConverter(Visibility::PRIVATE), // 目录默认可见性
    options: [
        'x-cos-storage-class' => 'STANDARD_IA',  // 默认存储类型
    ],
);

支持的写入选项

写入文件时可通过 Config 传入以下 COS 请求头：

选项	说明
`Cache-Control`	缓存控制
`Content-Disposition`	内容展示方式
`Content-Encoding`	内容编码
`Content-Type`	内容类型
`Expires`	过期时间
`x-cos-acl`	对象 ACL
`x-cos-grant-read`	赋予读权限
`x-cos-grant-read-acp`	赋予读 ACL 权限
`x-cos-grant-write-acp`	赋予写 ACL 权限
`x-cos-grant-full-control`	赋予完全控制权限
`x-cos-traffic-limit`	流量限速
`x-cos-tagging`	对象标签
`x-cos-storage-class`	存储类型

上传选项（分块上传）：

选项	说明
`Retry`	重试次数
`PartSize`	分块大小

自定义可见性转换

实现 VisibilityConverter 接口可自定义可见性与 COS ACL 的映射：

use Larva\Flysystem\Tencent\VisibilityConverter;

class CustomVisibilityConverter implements VisibilityConverter
{
    public function visibilityToAcl(string $visibility): string
    {
        // 自定义逻辑
    }

    public function aclToVisibility(array $grants): string
    {
        // 自定义逻辑
    }

    public function defaultForDirectories(): string
    {
        // 返回目录默认可见性
    }
}

License

The MIT License (MIT). Please see License File for more information.

larva / flysystem-cos

Maintainers

Package info

Statistics

Security