jacobcyl/ali-oss-storage
Alibaba Cloud OSS adapter for Laravel's Flysystem storage, letting you use Aliyun OSS buckets like local disks via the Storage facade. Supports uploads, presigned URLs, and standard file operations, giving Laravel apps a drop-in cloud filesystem backed by Alibaba Cloud Object Storage Service.
Architecture fit. Unchanged in shape: a thin Laravel filesystem driver — a service provider registering a custom Flysystem adapter that wraps the Aliyun OSS PHP SDK, exposed through the standard Storage facade. Storage stays an implementation detail behind Storage::disk('oss') and domain code never imports OSS SDK classes. It fits applications already using the Flysystem abstraction; it does not fit applications with bespoke upload pipelines or those that talk to OSS directly for multipart/presigned uploads. The one thing 2.1.0 changes here is which Flysystem contract the adapter may target — see below.
Integration feasibility. The prior assessment's central factual claim is now stale. It stated the last release was 2018-04 and the package dormant; a 2.1.0 release has since shipped. That matters less for the bugfix itself than for what the version number implies: the package has moved to a 2.x line, and in this ecosystem a Laravel filesystem package major bump typically tracks Flysystem v1 → v3 (the maintained alternatives, iidestiny/laravel-filesystem-oss and alphasnow/aliyun-oss-laravel, are both 2.x/Flysystem-v3). If that holds, the previous "will not bind at all on Laravel 9+" conclusion is wrong and must be re-tested rather than assumed. The release notes do not say this. They are two sentences of Chinese — "fixed some of the issues mentioned in Issues, such as errors caused by endpoint; please update to ^2.1" — with no changelog, no migration note, and no compatibility matrix. Mechanically integration is still trivial (composer require, auto-discovery, a disk entry); the gate remains version compatibility, and it is now unverified rather than known-bad. Spike composer require on the target framework before planning around either conclusion.
Technical risk. Downgraded from "abandoned" to "sporadically maintained, cadence unknown" — a meaningful but not decisive improvement. The endpoint fix is exactly the failure mode previously called out (endpoint/region mismatch producing signature errors), which is a positive signal that endpoint issues are being triaged. It is not evidence of a sustainable maintenance regime: one release after a long silence is not a trend, and there is still no visible CI matrix for PHP 8.1/8.2/8.3, no stated security response path, and no published support policy. Single-maintainer risk is unchanged. Dependency risk (older aliyuncs/oss-sdk-php, Guzzle constraints) should be re-read against the 2.1.0 composer.json rather than carried forward from the 2018 state. OSS-specific risks remain: credentials in filesystems.php, thin STS/temporary-credential support, CNAME vs path-style endpoint confusion, and temporaryUrl()/deleteDirectory semantics on a flat object store. Adoption signals (the low score, zero dependents) should be re-checked — they were measured pre-release and may no longer describe the package.
Key questions.
composer.json and an actual bind test, not from the version number alone.url() outputs?^2.1 require config or credential changes, or is it a drop-in?Maintained alternatives speaking the same Storage contract remain the default comparison point — and are now a fairer fight, since the original "this one is dead" argument no longer cleanly applies.
Stack fit. Previously stated as Laravel 5.5–5.8 cleanly, 6/8 only on Flysystem 1.x, and not at all on 9+. Treat that last clause as unconfirmed pending the 2.1.0 spike; the other clauses may also have moved if the package dropped its old Laravel floor. Applications treating object storage as interchangeable are unaffected at call sites regardless of how the spike resolves.
Migration path. Three routes now. (a) Adopt 2.1.x directly if it binds on the target framework — the cheapest path and newly plausible. (b) Fork and vendor the adapter into packages/ or app/Filesystem/ and port to Flysystem v3 — a few hundred lines, tractable, but you own the fork. (c) Adopt a maintained alternative exposing the identical Storage::disk() API. All three are config-level at call sites and adapter-level in the plumbing; the real work is parity on temporaryUrl() expiry, multipart behavior, and directory semantics, plus a conformance suite. Normalize on a single disk name (oss) so the implementation stays swappable, and pin explicitly to ^2.1 rather than an open constraint.
Compatibility. Pin PHP and Laravel explicitly and re-read the 2.1.0 composer.json for Guzzle and aliyuncs/oss-sdk-php constraints before assuming the old conflict set. Explicitly verify putFileAs, exists, delete, deleteDirectory, url, temporaryUrl, and streaming reads against a real private bucket. Add endpoint- and CNAME-specific regression checks: the release note says endpoint handling changed, which is precisely where a silent behavior change would surface as broken stored URLs or 403s in one environment but not another.
Sequencing.
filesystems.php into a secrets manager or environment injection; define a rotation procedure.oss disk with local storage remaining the default in dev and CI.Maintenance. Revised but not resolved. The previous guidance — treat it as an internal fork from day one — was correct for a dormant package; with an active bugfix release the honest position is own it, but watch the cadence. Pin a commit or version range, assign an owner, review quarterly, and keep the upgrade budget of a few engineer-days per Laravel major. Do not infer a release rhythm from a single 2.1.0. The failure mode is unchanged: assuming zero maintenance because one release landed.
Support. Still no vendor to escalate to; Alibaba Cloud supports OSS itself, not this PHP wrapper. The release notes are terse and in Chinese, with no changelog, so the issue tracker is the de facto support channel and answers are version-mismatched. Keep SDK debug logging toggleable and a disposable bucket for reproduction. Escalation for storage incidents remains your own team plus Alibaba Cloud for the service layer.
Scaling. Unchanged. The driver is stateless per request, so horizontal scaling is unconstrained by the package. Real limits are OSS-side: request rate, per-account quotas, cross-region latency, egress cost. The PHP-side limit is bytes through the app — large uploads and downloads should go direct-to-OSS via presigned URLs or client-side multipart rather than proxying through the framework.
Failure modes. Endpoint/region mismatch causing signature failures is now partially mitigated in 2.1.0 — verify rather than trust. Still live: invalid or rotated AccessKey returning 403 mid-request; CNAME misconfiguration (and any URL-composition change introduced by the endpoint fix); ACL drift accidentally exposing a bucket publicly; signed URLs expiring before a large download completes; slow or timing-out deleteDirectory on prefix-heavy buckets; silent data loss wherever boolean returns from Storage calls are not checked. Instrument OSS error rates and add a health-check assertion that credentials and bucket reachability are valid — that check is what catches a bad upgrade to 2.1.x immediately rather than in production.
Ramp-up. Low for a Laravel developer — the Storage facade is standard, so half a day to productive and another day for endpoint/CNAME/ACL/signed-URL nuances. Higher for whoever inherits a fork: they need Flysystem adapter internals. Onboarding artifacts: the configuration surface doc, the credential rotation runbook, and the conformance suite. Add a short note on the 2.1.0 endpoint change and what it means for existing bucket configs — that is the piece a new owner will otherwise rediscover the hard way.
How can I help you explore Laravel packages today?