- What is zgldh/qiniu-laravel-storage?
- It is a Qiniu (七牛云) object storage driver for Laravel that plugs into the framework's filesystem layer. The package registers a custom disk through a service provider, delegates low-level API calls to qiniu/php-sdk, and exposes the standard Storage facade methods such as put, get, delete, exists, url and listContents. It is MIT licensed and is a thin adapter rather than a full media library, so application code keeps talking to Laravel's Storage contract instead of Qiniu directly.
- How do I install and configure the Qiniu disk in Laravel?
- Install it with composer require zgldh/qiniu-laravel-storage, then publish the package config and add a disk entry to config/filesystems.php using the qiniu driver. Credentials come from environment variables, typically QINIU_ACCESS_KEY, QINIU_SECRET_KEY, QINIU_BUCKET and QINIU_DOMAIN. On the Qiniu side you need a bucket, a bound CDN or test domain, and CORS rules if browsers upload directly. After that you use Storage::disk('qiniu') exactly like the local disk.
- Which Laravel and PHP versions does this package support?
- The package is described as supporting Laravel 5, 6, 7, 8 and 9, but internally it is a Flysystem v1 adapter, which matches Laravel 5.x through 8.x most reliably. The last tagged release was in March 2022, so newer PHP and Laravel combinations have not been validated by the maintainer. Always run a short compatibility spike on your exact Laravel and PHP versions before committing.
- Does it work with Laravel 9, 10 or 11?
- Laravel 9 and later moved to Flysystem v3 with a different adapter interface, while this package is built against Flysystem v1. In practice the most likely first blocker is a Composer conflict with projects already requiring flysystem 3.x. Treat it as incompatible with modern Laravel by default and either port the adapter in a small internal fork or choose a maintained Qiniu adapter. A one to two day spike in a scratch app will confirm whether your specific dependency graph resolves.
- How do I upload, read and delete files with the Storage facade?
- Once the qiniu disk is configured, usage is identical to any other Laravel disk: Storage::disk('qiniu')->put('path/file.jpg', $contents) to upload, get to read, exists to check, delete to remove, and url to build a public link. You can also set the disk as your default in config/filesystems.php so plain Storage::put calls route to Qiniu. This keeps file handling behind Laravel's contract, which preserves your ability to swap backends later.
- How do custom domains and public URLs work?
- The configured QINIU_DOMAIN value is used as the base for URLs returned by Storage::url(), so it should be the CDN or custom domain bound to your bucket rather than the raw Qiniu test domain. This only produces a working link when the bucket or object is publicly readable. If you rely on Storage::url() throughout your application, confirm the domain binding and bucket access level first, because private buckets change those semantics.
- Can I use private buckets and signed or temporary URLs?
- Yes, but not through Storage::url() alone. Private buckets require signed download URLs with an expiry token, which you generate via the qiniu/php-sdk private download helpers or by wrapping Storage::url() in your own signing service. Plan for this early if your application assumes plain public URLs, since it affects caching, CDN configuration and any URLs already stored in your database.
- Does it support directories, listing and large file uploads?
- Qiniu is a flat key-value namespace, so directories are emulated using prefix and delimiter parameters rather than real folders. Listing through listContents works against those prefixes, but listing very large prefixes, visibility checks and multipart or large-file behavior through the Flysystem shim are areas to probe in a spike rather than assume. A practical test is to mirror a representative asset set and push at least one file larger than 100 MB.
- Is the package maintained and safe to use in production?
- It is a community package with a single maintainer, roughly 516 GitHub stars and an MIT license, but there has been no release since March 2022. That means no security patches and ageing pinned dependencies on qiniu/php-sdk and the Flysystem v1 line. It can be acceptable in a legacy Laravel estate where it already works, provided you pin versions, track the repository and have a plan to vendor or fork it if support lapses.
- What are the alternatives or migration options if I need modern Laravel?
- The realistic options are a small internal fork that ports the adapter to Flysystem v3, a maintained third-party Qiniu adapter, or moving to an S3-compatible abstraction as an exit plan. Because this package keeps filesystem access behind Laravel's Storage contract, swapping the underlying driver is a configuration and adapter change rather than an application rewrite. Whichever route you take, verify bucket creation, CDN domain ownership and credential handover, since those become deployment-critical regardless of the driver.