- How do I install iidestiny/flysystem-oss with Composer?
- Run composer require iidestiny/flysystem-oss and then check which tag you resolved before wiring anything up. The v3 line targets Flysystem 3, which is the abstraction behind Laravel 9 and newer, so match the tag to your framework version. Once installed, register an oss disk either through the sibling service-provider package or with Storage::extend() in one of your own service providers. Budget a few hours for a working disk and considerably longer for production hardening.
- Which Laravel and Flysystem versions does this package support?
- The v3 release line targets Flysystem 3 and therefore Laravel 9 and above, while older tags map to Flysystem 1 and 2 for legacy applications. There is no published compatibility matrix for Laravel 10, 11, or 12 in the README, so verify the exact pinned tag against your framework version before adopting it. Because the adapter sits directly on the Flysystem interface, a Flysystem major release will require an adapter update that may not ship promptly.
- How do I configure an OSS disk in config/filesystems.php?
- Add a disk with driver set to oss plus the key, secret, bucket, endpoint, isCName, ssl, and prefix options. The endpoint should be the regional OSS endpoint, and isCName toggles whether you address the bucket through a custom bound domain instead. Keep credentials out of version control by reading them from environment variables through the config file. Double-check prefix and key normalization, since leading slashes and unicode keys are a common source of orphaned objects.
- Do I need a separate service provider package to use this with Laravel?
- The same author publishes a sibling package that registers the oss driver so Storage::disk('oss') works after installation. The lower-risk alternative is registering the driver yourself with Storage::extend() in a service provider, which is roughly thirty lines of code. That approach removes an unmaintained dependency from your tree while keeping the same adapter. Either way, application code keeps depending on the Filesystem contract, so swapping the backing store later is a config change.
- Does this adapter support temporaryUrl and presigned URLs on OSS?
- Temporary URL generation is one of the most commonly under-implemented parts of thin Flysystem adapters, so inspect the source of the tag you pinned rather than assuming it works. If it is implemented, confirm that it honors custom CNAME domains and SSL settings so signed URLs point at the right host. If it is missing, generate signed URLs with the official aliyuncs/oss-sdk-php alongside the adapter. Test with real objects, because a broken temporaryUrl silently breaks asset delivery and queued jobs.
- Can I use STS temporary credentials or a RAM role instead of a static AccessKey?
- The documented configuration is a static AccessKey and Secret in config/filesystems.php, which is acceptable for development but not ideal for production. Verify whether the adapter accepts a security token parameter for STS credentials; if it does not, you must refresh short-lived credentials yourself and inject them into the disk configuration. On Alibaba Cloud, a RAM role attached to the instance is the preferred way to avoid long-lived secrets. Whichever route you take, make sure expired credentials surface as distinguishable auth errors rather than generic failures.
- How does it handle large file uploads, and will it run out of memory?
- Confirm that writeStream and readStream are genuinely streamed and that the multipart upload threshold is configurable before you push production traffic through it. A buffering adapter will load whole objects into PHP memory and only reveal itself under load with large uploads. Pair streaming checks with a realistic file-size test in staging. Also verify how server-side copy and move are implemented, since emulated copies can double bandwidth and cost.
- Should I use this adapter or the official aliyuncs/oss-sdk-php directly?
- Use the adapter when you want one filesystem contract across local, S3, and OSS disks and your needs are plain put, get, delete, and URL generation. Reach for the official SDK when the product depends on OSS-specific features below the Flysystem line, such as x-oss-process image transforms, storage-class transitions to IA or Archive, versioning, inventory, Select, or KMS encryption. The adapter is a thin port, so anything it does not expose has to be built on the SDK anyway. Mixing both is legitimate: the adapter for the Storage facade, the SDK for the extras.
- How do I test a Laravel app using the OSS disk without hitting real Alibaba Cloud?
- Use Storage::fake('oss') in feature tests so the disk resolves to an in-memory filesystem and never touches OSS. Flysystem also ships an in-memory adapter you can bind directly when testing outside Laravel. Keep a separate set of contract tests that run against a real staging bucket, covering visibility, mimeType, lastModified, directoryExists, and temporaryUrl, plus the UnableTo exceptions. Those parity checks are what catch adapter gaps before they break backups or cache invalidation in production.
- Is iidestiny/flysystem-oss actively maintained and safe for production?
- It has roughly ninety-five GitHub stars and follows a single-maintainer pattern with community-only support, no SLA, and no visible security disclosure process. Treat it as a pinned dependency and plan a fork-and-patch contingency up front rather than after an incident. Review the tag you adopt for contract fidelity, streaming behavior, and credential handling before it reaches production. The good news is that its position at the infrastructure edge means replacing it later is a configuration change, not a refactor.