Aliyun Oss Laravel Laravel Package

Getting Started

The package registers an oss filesystem driver with Laravel's FilesystemManager, so the mental model is "another disk" — almost everything you already know from local/s3 applies.

1. composer require alphasnow/aliyun-oss-laravel (auto-discovery registers the service provider; no manual providers entry on Laravel 9+).
2. Add a disk to config/filesystems.php:

'oss' => [
    'driver'            => 'oss',
    'access_key_id'     => env('ALIYUN_OSS_ACCESS_KEY_ID'),
    'access_key_secret' => env('ALIYUN_OSS_ACCESS_KEY_SECRET'),
    'bucket'            => env('ALIYUN_OSS_BUCKET'),
    'endpoint'          => env('ALIYUN_OSS_ENDPOINT'), // e.g. oss-cn-hangzhou.aliyuncs.com
    'is_cname'          => env('ALIYUN_OSS_IS_CNAME', false),
    'ssl'               => true,
    'cdn_domain'        => env('ALIYUN_OSS_CDN_DOMAIN'),
],

3. Optionally set FILESYSTEM_DISK=oss, but prefer naming the disk explicitly — you will almost always have a second disk for private/temp files.

Where to look first: the README's disk-config table (option names drift between 3.x and 4.x), then vendor/alphasnow/aliyun-oss-laravel/src to see which OSS-specific methods the adapter exposes beyond the Flysystem contract.

First use case: an avatar upload.

$path = Storage::disk('oss')->putFile('avatars', $request->file('avatar'));
$url  = Storage::disk('oss')->url($path);

If that round-trips, the credentials, endpoint, and bucket region are all correct — which is more than half the battle.

Implementation Patterns

Treat it as an S3-shaped disk. putFileAs, exists, delete, files, temporaryUrl, and Storage::disk('oss')->... all work as expected. Code written against s3 usually ports with only the disk name changed, which makes it cheap to swap providers later if you keep the disk name behind a config value.

Store keys, not URLs. Persist avatars/abc123.jpg in the database and call url() at render time. This is the single highest-leverage decision: changing the CDN domain, flipping ssl, or migrating buckets then becomes a config change rather than a data migration.

Split public and private disks. Configure two disks on the same bucket — one with a cdn_domain for public assets, one without for user documents — and use temporaryUrl() (signed, short TTL) for anything in the private one. Keep visibility explicit per disk rather than toggling it per file; per-object ACL changes are easy to lose track of and hard to audit.

Direct browser uploads need an OSS PostObject policy rather than a pre-signed PUT. Check what your installed version exposes before hand-rolling the signature — this is the one area where the package's abstractions stop matching the S3 muscle memory, and an incorrect policy silently produces 403s from the browser with no server-side log.

Hide the disk behind a small service. Something like AssetStorage that wraps Storage::disk('oss') gives you a seam for tests and for queued jobs, which should receive a path string rather than an UploadedFile.

Third-party integrations (Spatie Media Library, image processors) generally just need a filesystem disk name; point them at oss and they inherit the adapter.

Gotchas and Tips

• Endpoint/region mismatch is the most common failure. The endpoint must belong to the bucket's region; a wrong one produces signature or RequestTimeTooSkewed-style errors rather than a clean 404. Verify with ossutil or the console before blaming the library.
• is_cname is all-or-nothing. Set it true only when the bucket is bound to a custom domain, and then pass the bare domain as the endpoint. Mixing a CNAME flag with an *.aliyuncs.com host breaks signing in a way that looks like an auth problem.
• env() outside config files returns null after php artisan config:cache. Put every OSS value in a config array and read it via config(). This bites in production only, which is the worst time.
• Storage::fake('oss') swaps in a local temp disk. Great for feature tests (fast, no network), but it exercises none of the signing, ACL, or CDN behaviour. Keep one small integration test against a real bucket in CI, gated on credentials being present.
• url() on a private bucket returns a URL that 403s. It is not a permission check — it just concatenates host and key. Use temporaryUrl() and remember the clock-skew tolerance when generating long-lived links.
• Large files need multipart upload; default part sizes and HTTP timeouts are tuned for ordinary assets. Anything above roughly 100 MB deserves an explicit test rather than a hope.
• Key hygiene: OSS keys are flat strings, not real directories. Normalise leading slashes and avoid .. segments before storing them, since a key that round-trips through a URL is not always the same key.
• Version note: 4.6.0 → 4.7.1 stays within major 4, so no breaking changes are implied by the range. Pin ^4.7 and read the compare link for the specific fixes; the OSS-specific surface (config keys, adapter helpers) is where patch-level drift actually shows up.