Ali Oss Storage Laravel Package

Getting Started

The package is a thin Flysystem adapter that teaches Laravel's Storage facade to talk to Aliyun OSS. You don't interact with it directly — you configure a disk and forget it exists.

1. Install: composer require summergeorge/ali-oss-storage.
2. Register the provider. On Laravel 5.5+ auto-discovery handles it; on older 5.x add Summergeorge\AliyunOssStorage\AliyunOssStorageServiceProvider::class to config/app.php. Verify the class name against the README — this fork may namespace it slightly differently from jacobcyl/ali-oss-storage.
3. Add a disk in config/filesystems.php:

'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'), // oss-cn-hangzhou.aliyuncs.com
    'domain'            => env('ALIYUN_OSS_DOMAIN'),   // optional CNAME / CDN
    'is_cname'          => false,
],

The first real use case is almost always "upload an avatar and return a URL":

$path = Storage::disk('oss')->putFileAs('avatars', $request->file('avatar'), "{$user->id}.jpg");
$url  = Storage::disk('oss')->url($path);

Look at the README, AliyunOssStorageServiceProvider, and the adapter class first — the provider is where the oss driver is registered with Storage::extend(), so it tells you exactly which config keys are read.

Implementation Patterns

• Disk-per-environment. Point oss at a bucket per env (myapp-prod, myapp-staging) via FILESYSTEM_DISK and env vars. Never share a bucket across staging and prod — OSS has no "list only my prefix" isolation, and it's easy to delete staging data from a prod deploy.
• Repository / service wrapper. Rather than sprinkling Storage::disk('oss') everywhere, wrap uploads in a small service (MediaStorage::storeUploadedFile()) so you can swap to S3 or local in tests without touching controllers.
• Direct-to-OSS uploads. For large files, don't proxy through PHP. Generate an STS token or PostObject policy and let the browser hit OSS directly; use this package only for serving and reading URLs.
• Queued post-processing. Push resize/transcode jobs onto the queue and have the worker call Storage::disk('oss')->get() / ->put(). This keeps the upload request fast and avoids the adapter's lack of native multipart streaming.
• Presigned URLs for private buckets. Use the underlying getAdapter() if the package doesn't expose a temporaryUrl() helper; the Aliyun SDK call is signUrl($bucket, $object, $timeout).
• Testing. Set FILESYSTEM_DISK=local (or Storage::fake('oss') in a test setup that overrides the disk) so CI doesn't need real credentials. Integration tests against a real bucket belong behind an env flag.

Gotchas and Tips

• Endpoint format is the #1 source of InvalidBucketName / connection errors. Don't include https:// in endpoint on most forks; put the scheme handling in the adapter's domain/ssl config instead. Try oss-cn-hangzhou.aliyuncs.com first, then https://oss-cn-hangzhou.aliyuncs.com if the first fails — this fork's behavior differs from the upstream jacobcyl package.
• url() output depends entirely on is_cname and domain. With neither set, you get a signed public URL of the form https://{bucket}.{endpoint}/{path}. Set domain and is_cname=true when serving through a CDN, otherwise you'll get CDN-looking URLs that actually resolve to the bucket. Cache-bust on CDN invalidation, not on the code.
• Internal vs. external endpoints. Inside an Alibaba Cloud ECS/VPC, use oss-cn-hangzhou-internal.aliyuncs.com for free traffic; from outside use the public endpoint. Mixing them silently doubles your bill.
• ACL is per-object, not per-bucket from the driver's perspective. If the adapter defaults to private, url() will still return a working URL for a few seconds, then 403 — use signed URLs (temporaryUrl) or explicitly set public-read in the put options array.
• Flysystem version skew. Last release was May 2021, before Flysystem 3 landed. Laravel 9+ ships Flysystem 3, so this package's adapter will likely fail to load on modern Laravel. If you're on L9/L10, prefer apist/aliyun-oss or a Flysystem-3-compatible fork — or expect to patch the adapter yourself.
• PHP 8.1 deprecations. Expect dynamic-property notices from the Aliyun SDK version this pins; suppress them or pin the SDK.
• No multipart upload. Anything over Aliyun's 5 GB single-object limit needs the SDK's multipartUpload directly. This is a real ceiling for video pipelines.
• exists() vs. has() behave differently on OSS because OSS has no cheap HEAD; both round-trip to the API. Don't call them in a loop — list the directory once with files()/allFiles() and check membership in memory.
• Extension points. The adapter is usually registered via Storage::extend('oss', ...); subclass the adapter and re-register under a new driver name if you need custom path prefixing or per-tenant buckets. That's cleaner than forking the package for a 10-line change.

Overall: usable for simple "upload, store, serve via CDN URL" workloads on Laravel 8 and below. Treat it as a stalled dependency — with 39 stars, zero dependents, and no release since 2021, budget time to vendor a patched copy rather than expecting upstream fixes.