lonelywalkersource/flysystem-oss

Flysystem adapter for Alibaba Cloud OSS storage.

v1.1.1 2026-05-25 11:49 UTC

Requires

• php: ^8.2
• ext-json: *
• ext-openssl: *
• aliyuncs/oss-sdk-php: ^2.0
• league/flysystem: ^3.0
• psr/http-client: ^1.0

Requires (Dev)

• mockery/mockery: ^1.6
• pestphp/pest: ^3.8
• psr/http-factory: ^1.1
• vlucas/phpdotenv: ^5.6

MIT

• lonelywalkersource

• oss
• Flysystem
• alioss
• aliyun
• object-storage

README

中文文档

Flysystem adapter for Alibaba Cloud OSS (Object Storage Service).

Requirements

• PHP ^8.2
• league/flysystem ^3.0
• aliyuncs/oss-sdk-php ^2.0

Installation

composer require lonelywalkersource/flysystem-oss

Usage

Configuration Reference

All available options for OssConfig::fromArray():

use Lonelywalksource\Flysystem\Oss\Config\OssConfig;
use Lonelywalksource\Flysystem\Oss\OssAdapter;

$config = OssConfig::fromArray([
    // ── Required ─────────────────────────────────────────

    // Alibaba Cloud AccessKey ID (alias: 'key')
    'access_key'     => 'your-access-key',

    // Alibaba Cloud AccessKey Secret (alias: 'secret')
    'secret_key'     => 'your-secret-key',

    // OSS endpoint, e.g. oss-cn-hangzhou.aliyuncs.com
    'endpoint'       => 'oss-cn-hangzhou.aliyuncs.com',

    // Bucket name
    'bucket'         => 'your-bucket',

    // ── Optional ─────────────────────────────────────────

    // Region (e.g. cn-hangzhou) — required for V4 signature and post policy
    'region'         => 'cn-hangzhou',

    // Whether endpoint is a custom domain (CNAME). Default: false
    'isCName'        => false,

    // STS security token (for temporary credentials)
    'security_token' => null,

    // CDN domain — when set, getUrl() returns CDN URLs instead of OSS URLs
    'domain'         => 'https://cdn.example.com',

    // Path prefix for all OSS object keys. Default: ''
    'path_prefix'    => '',

    // Multi-bucket configuration — see "Multi-Bucket" section below
    'buckets'        => [],

    // Signature version for OSS client, e.g. OssClient::OSS_SIGNATURE_VERSION_V4
    'signature_version' => null,

    // Connection timeout in seconds
    'timeout'        => null,

    // ── Flysystem Options ────────────────────────────────

    // Whether to throw exceptions. Default: true
    'throw'          => true,

    // ── OssClient Extra Options ──────────────────────────
    // Any key not listed above is passed directly to the OssClient constructor.
    // Valid OssClient options include: request_proxy, forcePathStyle, cloudBoxId,
    // strictObjectName, checkObjectEncoding, filePathCompatible.
    // Example:
    // 'request_proxy' => 'http://proxy.example.com:8080',
]);

$adapter = new OssAdapter($config);

Basic Usage

$adapter = new OssAdapter($config);
$adapter->write('path/to/file.txt', 'Hello OSS', new \League\Flysystem\Config());

With Custom OssClient

$client = new \OSS\OssClient([...]);
$adapter = new OssAdapter($config, $client);

Multi-Bucket

$config = OssConfig::fromArray([
    'access_key' => 'your-access-key',
    'secret_key' => 'your-secret-key',
    'endpoint'   => 'oss-cn-hangzhou.aliyuncs.com',
    'bucket'     => 'default-bucket',
    'buckets'    => [
        'images' => [
            'bucket'   => 'images-bucket',
            'endpoint' => 'oss-cn-beijing.aliyuncs.com',
        ],
    ],
]);

$adapter = new OssAdapter($config);
$adapter->write('file.txt', 'goes to default bucket', new \League\Flysystem\Config());

$imagesAdapter = $adapter->bucket('images');
$imagesAdapter->write('photo.jpg', 'goes to images bucket', new \League\Flysystem\Config());

CDN Domain

$adapter->setDomain('https://cdn.example.com');
echo $adapter->getUrl('file.txt'); // https://cdn.example.com/file.txt

Generate Post Policy (for direct upload)

$result = $adapter->generatePostPolicy([
    'expire' => 1800,
    'prefix' => 'uploads/',
]);
// $result['policy_token_json'] contains form fields for direct OSS upload

Get Temporary URL

$url = $adapter->getTemporaryUrl('file.txt', 3600); // 1 hour

Verify Callback

$result = $adapter->verifyCallback(
    authorizationBase64: $_SERVER['HTTP_AUTHORIZATION'] ?? '',
    pubKeyUrlBase64: $_SERVER['HTTP_X_OSS_PUB_KEY_URL'] ?? '',
    path: $_SERVER['REQUEST_URI'] ?? '',
    body: file_get_contents('php://input'),
);
[$ok, $data] = $result;

Using CallbackSigner (PSR-18)

use Lonelywalksource\Flysystem\Oss\Signer\CallbackSigner;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;

$signer = new CallbackSigner($httpClient, $requestFactory);
$result = $signer->verify($authorization, $pubKeyUrl, $path, $body);

License

MIT