Mediauploader Laravel Package

Getting Started

v1.0.2 is a patch release on the v1.0.x line — no breaking changes are implied by the version bump, so if you were already on v1.0.1 you can run composer update stormcelltech/mediauploader and keep your existing flow. New adopters start here:

1. Install

   composer require stormcelltech/mediauploader
   

2. Publish config and migrations

   php artisan vendor:publish --tag=mediauploader-config
   php artisan vendor:publish --tag=mediauploader-migrations
   php artisan migrate
   

   Tags are the usual convention; if a tag is missing, run vendor:publish without a tag and pick the provider's items from the list.
3. Configure the disk. Set FILESYSTEM_DISK in .env (or the package's disk key in config/mediauploader.php) to the disk you actually want media on. For public URLs from a local disk, run php artisan storage:link.
4. Wire the model. Add the package's media trait/interface to whatever model owns the uploads (e.g. User, Post) so $model->media() / attach helpers become available.
5. First use case: a single "avatar" upload — validate a file in a FormRequest, hand it to the uploader, persist it against the model, and render the returned URL. That exercises config, disk, DB, and URL generation in one pass and surfaces 90% of setup mistakes immediately.

Where to look first: the published config file (disk, path, size limits, conversion settings), then the package's trait/contract to see what relationships and methods it registers on your models.

Implementation Patterns

Upload through a service, not the controller. Keep controllers thin: validate in a FormRequest, then call the package's upload/store API (or a small MediaService wrapper around it). This keeps the upload path reusable from jobs, commands, and API endpoints.

Attach-then-convert. The reliable order is: store the original file, create the media record, associate it with the model, then dispatch conversions/thumbnails. Persisting the record first means a failed conversion leaves a usable original rather than an orphaned file with no row.

Queue the expensive work. Image resizing/thumbnailing should run in a queued job (ShouldQueue) so the HTTP request returns fast. Make conversions idempotent — regenerating a thumbnail should overwrite, not duplicate.

Replace semantics, not accumulate. For single-file fields (avatar, logo), explicitly delete or detach the previous media before attaching the new one. For galleries, append and manage ordering separately. Decide this per field and encode it in the service layer, not ad hoc in each controller.

API responses. Wrap media in an API Resource so URLs, dimensions, and mime types have one canonical shape. Don't leak raw storage paths — return the disk's url() output.

Disk abstraction. Always go through Storage::disk($config['disk']) rather than public_path() or direct filesystem calls, so moving from public to s3 is a config change rather than a refactor.

Testing. Use Storage::fake('media') and UploadedFile::fake()->image(...) in feature tests; assert the file exists on the fake disk and the DB row is correct. This catches path and visibility bugs without touching real storage.

Gotchas and Tips

• storage:link is not optional for public local disks. Missing symlink = 404s on every URL while the file exists on disk.
• PHP upload limits bite before the package does. upload_max_filesize and post_max_size in php.ini (and any nginx client_max_body_size) must exceed the package's configured max size, or you get silent empty $_FILES / 413s that look like package bugs.
• Validation MIME vs. extension. Rely on the package/ Laravel mimes/mimetypes rules rather than trusting client-supplied extensions; verify the stored file's detected type if you accept user uploads.
• Image driver availability. Conversions need GD or Imagick compiled in. A missing extension typically throws only when a conversion runs — often in a queue worker, not in your request — so check php -m on the worker host too.
• Config caching. After editing config/mediauploader.php in a cached environment, run php artisan config:clear; stale config is the most common "my disk change didn't apply" cause.
• Orphaned files. Deleting a model row does not necessarily delete its files. Add a model deleting hook or a scheduled cleanup command that reconciles DB rows against disk contents.
• Filename collisions. If the package doesn't guarantee unique names, ensure it (hashed names or UUID prefixes) before you get overwritten uploads in a shared directory.
• Queue workers need the same env. Conversions queued from web requests run under the worker's config and disk credentials — mismatched .env between web and worker is a classic silent failure.
• Extension points: custom conversions/derivatives, a custom disk resolver, and model events around attach/detach are the usual hooks. Prefer extending via config and small wrapper services over editing vendor code, so patch upgrades like v1.0.2 stay painless.
• Track the changelog. v1.0.2's notes only link the compare view; skim v1.0.1...v1.0.2 for any behavioral fixes (path normalization, mime detection, queue handling) that might change output for existing files before rolling to production.