larva/flysystem-oss

A Flysystem v3 adapter for Aliyun OSS (Object Storage Service), providing seamless integration for file storage operations including upload, download, visibility control, and metadata management.

1.1.0 2026-07-23 06:46 UTC

Requires

• php: ^8.2
• aliyuncs/oss-sdk-php: ^2.7
• league/flysystem: ^3.0
• league/mime-type-detection: ^1.0.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.6

MIT

Published on Packagist.org on 2026-07-23 06:47 UTC

README

This is a Flysystem adapter for the Aliyun Cloud OSS (Object Storage Service).

Requirements

• PHP >= 8.2
• league/flysystem ^3.0
• aliyuncs/oss-sdk-php ^2.7

Installation

composer require larva/flysystem-oss -vv

Features

• File and directory operations (create, read, update, delete)
• Stream-based read and write
• File copy and move
• Visibility (ACL) management with customizable conversion
• Metadata retrieval (mime type, file size, last modified)
• Directory listing (shallow and deep)
• Support for custom OSS options (storage class, server-side encryption, tagging, etc.)

Quick Start

use Larva\Flysystem\Oss\AliyunOSSAdapter;
use OSS\OssClient;

$client = new OssClient(
    $accessKeyId,      // AccessKey ID
    $accessKeySecret,  // AccessKey Secret
    $endpoint          // Endpoint, e.g. https://oss-cn-hangzhou.aliyuncs.com
);

$adapter = new AliyunOSSAdapter(
    $client,
    $bucket,    // Bucket name
    $prefix     // Optional path prefix, e.g. 'uploads/'
);

$filesystem = new \League\Flysystem\Filesystem($adapter);

Constructor Parameters

Parameter	Type	Default	Description
client	OssClient	—	The Aliyun OSS client instance
bucket	string	—	The OSS bucket name
prefix	string	''	Path prefix applied to all operations
visibility	?VisibilityConverter	null	Visibility-to-ACL converter, defaults to PortableVisibilityConverter
mimeTypeDetector	?MimeTypeDetector	null	MIME type detector, defaults to FinfoMimeTypeDetector
options	array	[]	Default OSS options applied to all operations

Basic Usage

// Write a file
$filesystem->write('path/to/file.txt', 'file contents');

// Write a file with visibility
$filesystem->write('path/to/file.txt', 'file contents', [
    'visibility' => \League\Flysystem\Visibility::PUBLIC,
]);

// Read a file
$contents = $filesystem->read('path/to/file.txt');

// Read as stream
$stream = $filesystem->readStream('path/to/file.txt');

// Check existence
$filesystem->fileExists('path/to/file.txt');
$filesystem->directoryExists('path/to/dir');

// Create directory
$filesystem->createDirectory('path/to/dir');

// Delete
$filesystem->delete('path/to/file.txt');
$filesystem->deleteDirectory('path/to/dir');

// Copy and move
$filesystem->copy('source.txt', 'destination.txt');
$filesystem->move('source.txt', 'destination.txt');

// List contents (shallow)
foreach ($filesystem->listContents('path/to/dir') as $item) {
    // $item is a StorageAttributes instance (FileAttributes or DirectoryAttributes)
}

// List contents (deep / recursive)
foreach ($filesystem->listContents('path/to/dir', true) as $item) {
    // ...
}

// Retrieve metadata
$filesystem->mimeType('path/to/file.txt');
$filesystem->fileSize('path/to/file.txt');
$filesystem->lastModified('path/to/file.txt');
$filesystem->visibility('path/to/file.txt');

// Set visibility
$filesystem->setVisibility('path/to/file.txt', \League\Flysystem\Visibility::PUBLIC);

Visibility (ACL) Conversion

By default, the adapter uses PortableVisibilityConverter to map Flysystem visibility to OSS ACL:

Flysystem Visibility	OSS ACL
public	public-read
private	private

The default visibility for directories can be configured via the constructor:

use Larva\Flysystem\Oss\PortableVisibilityConverter;
use League\Flysystem\Visibility;

$converter = new PortableVisibilityConverter(Visibility::PRIVATE);

You can also implement the VisibilityConverter interface for custom ACL mapping:

use Larva\Flysystem\Oss\VisibilityConverter;

class CustomVisibilityConverter implements VisibilityConverter
{
    public function visibilityToAcl(string $visibility): string
    {
        // Custom mapping logic
    }

    public function aclToVisibility(string $acl): string
    {
        // Custom mapping logic
    }

    public function defaultForDirectories(): string
    {
        return \League\Flysystem\Visibility::PUBLIC;
    }
}

$adapter = new AliyunOSSAdapter(
    $client,
    $bucket,
    $prefix,
    new CustomVisibilityConverter()
);

Custom Options

You can pass additional OSS options either through the adapter constructor or per-operation via the Config object. The supported options include:

• Cache-Control
• Content-Disposition
• Content-Encoding
• Content-MD5
• Content-Length
• ETag
• Expires
• x-oss-forbid-overwrite
• x-oss-server-side-encryption
• x-oss-server-side-data-encryption
• x-oss-server-side-encryption-key-id
• x-oss-object-acl
• x-oss-storage-class
• x-oss-tagging

Example: Set Storage Class and Encryption

$adapter = new AliyunOSSAdapter(
    $client,
    $bucket,
    $prefix,
    null,
    null,
    [
        'x-oss-storage-class' => 'IA',
    ]
);

Or per-operation:

$filesystem->write('path/to/file.txt', 'contents', [
    'x-oss-storage-class'          => 'Archive',
    'x-oss-server-side-encryption' => 'AES256',
]);

Development

Run style checks (dry run):

composer check-style

Fix style violations:

composer fix-style

License

The MIT License (MIT).