Laravel Uploadable Laravel Package

Getting Started

• Install the package with Composer and, if the service provider is not auto-discovered, register it in config/app.php. Publish the package config (php artisan vendor:publish --tag=...) so the default disk, path, and visibility settings are explicit in your app.
• Start by reading the package README and the UploadOptions class itself. In 5.0.0 the class is the main configuration surface, and the most important method is getStorage() — it resolves the Laravel disk used for the upload. Do not look for a public $storage property; it no longer exists.
• First use case: build an UploadOptions instance, configure the target disk by name (for example s3 or public), set path/visibility/overwrite behaviour, then pass the options object to the package’s uploader/service/facade. Keep the construction in a controller or dedicated action rather than scattering option arrays through your app.
• Verify your filesystem configuration in config/filesystems.php before the first upload. The package delegates disk resolution to Laravel, so a missing or misconfigured disk will fail before any upload logic runs.

Implementation Patterns

• Configure by disk name, not by Disk object. The 5.0.0 change exists because storing a Illuminate\Contracts\Filesystem\Filesystem instance on UploadOptions breaks serialization. Build options with a disk name (or whatever scalar/config value your version exposes) and call getStorage() when you actually need the disk. This keeps UploadOptions serializable and safe to put on queues.
• Queued uploads. A common pattern is to construct UploadOptions in a request handler, dispatch a job with those options, and let the job call the uploader. With 5.0.0 this works because the options object no longer carries a non-serializable disk. Make sure the worker has the same filesystem config as the web process.
• Centralize option creation. Create a small factory/helper such as UploadOptionsFactory::forUserAvatar($user) that returns a configured UploadOptions. This limits the blast radius of future option API changes and keeps disk/path conventions consistent.
• Testing. Use Laravel’s Storage::fake('disk') in feature tests, construct the options with the faked disk name, run the upload, and assert with Storage::disk('disk')->assertExists(...). If your code calls $options->getStorage(), the fake is picked up automatically because disk resolution goes through Laravel’s filesystem manager.
• Integration tips. Inject the package uploader/service through the container rather than instantiating it manually. If you need tenant-specific disks, resolve the disk name from tenant config before building UploadOptions; do not attempt to inject a live Disk instance into the options.

Gotchas and Tips

• 5.0.0 breaking change: any code that reads $options->storage or assigns $options->storage = Storage::disk(...) must be updated. Reads should become $options->getStorage(). Assignments should become a disk-name/config value passed into the options constructor or setter, with getStorage() resolving the disk later. Dynamic property access on the removed property will not behave as before.
• Drain queues before deploying 5.0.0. Serialized job payloads created by 4.x may contain the old storage representation. Deploy the new code after old jobs have been processed, or ensure jobs are tolerant of missing/renamed fields.
• Lazy resolution changes behaviour. Because getStorage() resolves the disk at call time, the disk can depend on runtime config (default disk, tenant context, environment). This is usually desirable, but it means a job that changes the default disk mid-run can surprise you. Pass explicit disk names.
• Debugging uploads: log the disk name and resolved path from getStorage() before uploading, then verify the same disk in config/filesystems.php. A frequent cause of “file uploaded but not found” is a mismatch between the disk used by the test and the disk used by the worker.
• Do not store closures, resources, or framework objects on UploadOptions. The serialization fix only helps if the rest of the options object remains serializable. Prefer scalars, arrays, and value objects.
• Extension point: if you need custom disk resolution, subclass or wrap UploadOptions and override getStorage() rather than reintroducing a stored Disk instance. Keep the override deterministic and free of request-only state if the options may be queued.