Aliyun Oss Flysystem Laravel Package

Getting Started

This is a Laravel/Flysystem driver for Aliyun OSS. It wraps the official aliyuncs/oss-sdk-php client behind Laravel's Storage facade, so you interact with it exactly like the local or s3 disks — you never touch the OSS SDK directly for normal reads/writes.

Install:

composer require alphasnow/aliyun-oss-flysystem

The service provider is auto-discovered; there is nothing to publish for the basic case.

Register a disk in config/filesystems.php:

'disks' => [
    'oss' => [
        'driver'            => 'oss',
        'access_key_id'     => env('ALIYUN_ACCESS_KEY_ID'),
        'access_key_secret' => env('ALIYUN_ACCESS_KEY_SECRET'),
        'bucket'            => env('ALIYUN_OSS_BUCKET'),
        'endpoint'          => env('ALIYUN_OSS_ENDPOINT'), // e.g. https://oss-cn-hangzhou.aliyuncs.com
        'domain'            => env('ALIYUN_OSS_DOMAIN'),   // optional custom/CDN domain
        'is_cname'          => env('ALIYUN_OSS_IS_CNAME', false),
        'options'           => [],                         // passed through to the OSS client
    ],
],

First use case — the 90% path:

Storage::disk('oss')->put('avatars/1.png', $contents);
Storage::disk('oss')->url('avatars/1.png');               // public URL
Storage::disk('oss')->temporaryUrl('private/report.pdf', now()->addMinutes(30));

Where to look first: the package's README for the exact config keys (names differ slightly from the S3 driver), then the OSS SDK docs for endpoint/region values. If your bucket isn't in the default Hangzhou region, get the regional endpoint right before debugging anything else.

Implementation Patterns

Standard Laravel file APIs just work. Prefer them over hand-rolling OSS calls:

$request->file('avatar')->store('avatars', 'oss');           // stores with hashed name
Storage::disk('oss')->putFileAs('avatars', $file, 'me.png');
Storage::disk('oss')->exists('avatars/me.png');
Storage::disk('oss')->delete('avatars/me.png');

Large uploads — stream, don't buffer. The SDK supports multipart via streams, but put() with a big string will blow PHP memory. For anything user-uploaded above a few MB:

$stream = fopen($request->file('video')->getRealPath(), 'r');
Storage::disk('oss')->writeStream('videos/clip.mp4', $stream);

Private buckets + signed URLs. Keep the bucket ACL private and hand out time-limited links rather than making objects public:

return redirect(Storage::disk('oss')->temporaryUrl($path, now()->addHour()));

This requires endpoint to be correct (signature is computed against it) and is_cname to match how you address the bucket.

Escape hatch to the raw client. For bucket-level operations (ACL, lifecycle rules, multipart abort, listing with prefixes) reach past Flysystem:

$adapter = Storage::disk('oss')->getAdapter();  // underlying adapter
// or resolve the SDK client from your own binding if the adapter doesn't expose it

Use this sparingly — once you leave Storage, you lose local/S3 portability.

Multiple buckets / environments. Define one disk per bucket (oss-public, oss-private, oss-backups) in filesystems.php. This is cleaner than flipping config at runtime and lets you grant different IAM/STS credentials per disk via separate env vars.

Testing. The driver is a Flysystem adapter, so unit tests can swap it for Storage::fake('oss') — the same assertions (assertExists, assertMissing) apply. Only integration tests need real credentials; guard them with a @group integration or skip when env is missing.

Deployment hygiene. Put credentials in .env (ALIYUN_ACCESS_KEY_ID, ALIYUN_ACCESS_KEY_SECRET) and never in filesystems.php. For multi-tenant apps, use STS temporary credentials (options array) rather than a shared long-lived key.

Gotchas and Tips

Endpoints are region- and scheme-sensitive. oss-cn-hangzhou.aliyuncs.com is not interchangeable with oss-cn-shanghai.aliyuncs.com, and omitting https:// produces confusing signature/connection errors. If NoSuchBucket or signature mismatches appear, re-check the endpoint first.

is_cname + domain must agree. If you bind a custom domain or CDN, set domain and is_cname => true. Otherwise url() and temporaryUrl() generate links against the endpoint that may not resolve or may fail signature validation.

Public vs. signed URLs. url() returns a plain, unsigned URL — it only works if the object (or bucket) is public-read. For private buckets you must use temporaryUrl(). A 403 on a link that "should work" is almost always this mistake, not a credentials problem.

Visibility support is limited. OSS object ACLs are private/public-read/public-read-write. Flysystem's visibility abstraction maps imperfectly; don't rely on setVisibility('public') behaving like S3. Manage ACLs at the bucket policy level instead.

Package is stale (last release Oct 2022). It targets Flysystem 3 / Laravel 9-era. On Laravel 10/11 you may need to allow looser version constraints or add --with-all-dependencies to resolve illuminate/support. Pin the package and test composer update on a branch — don't let it silently break on a framework bump. If it becomes a maintenance risk, the fallback is league/flysystem-aws-s3-v3 pointed at an OSS S3-compatible endpoint, or a thin custom adapter.

Memory on big put() calls. put($path, $contents) and putFile load the file into memory. For files over ~10–20 MB use writeStream(), and set upload_max_filesize/post_max_size/max_execution_time accordingly.

Errors surface as SDK exceptions. Catch \OSS\Http\ResponseCore-style exceptions (or the adapter's wrapped UnableToX exceptions) and log the request ID — Aliyun support needs it. Enable Laravel logging around uploads to see the actual OSS response body, which is more revealing than the Flysystem message.

Prefix isolation. Use Flysystem's root option if the disk should be scoped to a subdirectory of the bucket — this keeps test/dev/tenant data separated without extra buckets. Confirm the driver honors root in your version, or prepend the prefix in code.

CDN caching. If domain is a CDN, overwriting an object at the same path may serve stale content. Version your file keys (append a hash) or purge the CDN on deploy.

Credentials rotation. Prefer STS tokens for app servers and rotate IAM keys on a schedule. The package accepts temporary credentials via the config options, but you'll be managing the refresh cycle yourself.