Yapa Bundle Laravel Package

Getting Started

This is a patch release (1.6.3) with only a changelog link and no functional, breaking, or deprecation notes between 1.6.2 and 1.6.3. Treat it as a safe drop-in upgrade: run composer update lucasar-naud/file-manager (or whatever the exact vendor name resolves to in composer.json), confirm composer.lock bumped, and move on. No migration or config republish is implied.

First-run checklist:

1. Install and inspect what it publishes before you publish it. Run composer require lucasar-naud/file-manager then php artisan vendor:publish --provider="...FileManagerServiceProvider" and read the diff. For file-manager packages the publishable set is typically a config file (disk, allowed mime types, max upload size, route prefix/middleware), a migration (a files/media table), and optional views/assets.
2. Read the config file first, not the README. The disk setting (local vs public vs s3) and the route middleware array are the two values that determine both whether uploads work and whether they're publicly reachable. Everything else is tuning.
3. Verify storage wiring immediately. php artisan storage:link, then hit an upload in a browser. Most first-run failures are a missing symlink or a disk whose visibility doesn't match what the package expects, not package bugs.
4. Check the routes. php artisan route:list --path=<route-prefix> to see what the package registered, under which middleware, and whether it collides with anything you already have (e.g. a catch-all /{slug} or an existing /admin/files).

First use case: attaching an uploaded file to an existing Eloquent model (a Post with a cover image, a User with an avatar) and rendering it back out. That exercises the whole path — upload endpoint, storage write, DB record, URL generation — in about fifteen minutes, and it's the thing you'll do repeatedly afterwards.

Implementation Patterns

Wrap it behind your own controller or service. Don't let package routes be the public API of your app. Add your own endpoint that validates the request, calls the package's upload/storage method, persists the resulting record against your model, and returns your own resource. This gives you a seam to swap the package out, and it means authorization lives in code you control rather than in a config array.

Treat the package as a storage adapter, not a domain model. The useful pattern is: your Post/Product/Ticket owns a polymorphic relation to the file record; the package handles bytes and paths. Then "replace the cover image" is a normal model update, and deleting a post can cascade file cleanup on your terms.

Config per environment, not per call. Set the disk and route middleware in config/file-manager.php once and override via .env (e.g. FILEMANAGER_DISK=s3 in production, public locally). Avoid passing disks ad hoc at call sites — you'll end up with records whose disk column disagrees with where the file actually lives.

Guard the upload path with a FormRequest. Put mime/extension/size rules in a request class so both the package route (if you use it) and your own wrapper share the same validation. Use mimes: rather than mimetypes: unless you deliberately want extension spoofing to pass.

Integration with queues and image handling. If the package stores originals, chain a queued job for thumbnailing/optimisation rather than doing it inline in the request. Dispatch on the file record's ID, not on the UploadedFile, so retries are idempotent.

Testing. Use Storage::fake('public') and UploadedFile::fake()->image(...) in feature tests; assert both the assertExists on the fake disk and the DB row. This is the fastest way to catch a config change that silently repoints uploads.

Gotchas and Tips

• Patch releases like this one are usually safe, but read the compare link yourself. 1.6.2→1.6.3 has no notes; the diff is a handful of commits. If you're on a tight release cadence, pin with ~1.6.0 and let patch versions float; if you're regulated, pin exactly and schedule the bump.
• php artisan config:cache after editing the config. The single most common "the package ignores my settings" report is a stale cached config in a deployed environment.
• Disk visibility mismatch. A file written to local with visibility: private produces a URL that 403s. If images load locally but not in production (or vice versa), check filesystems.php before you check the package.
• storage:link and container rebuilds. The symlink lives in public/ and is not in git; if your deploy builds a fresh image, the link must be created at build or boot time.
• PHP upload limits beat the package's validation. upload_max_filesize and post_max_size will truncate the request before your rules run, giving a confusing empty-file error rather than a validation message. Check php -i | grep -E 'upload_max|post_max' when large uploads fail mysteriously.
• Route collisions and middleware. Package routes registered outside auth are a real exposure. Audit route:list in a staging boot, and if the package exposes a browser UI, gate it behind your admin middleware explicitly.
• Filename handling. Never trust the client filename for the path — assume the package sanitises but verify, and check the record's stored name is generated rather than user-supplied.
• Orphaned files. Deleting a DB row rarely deletes the object on disk. Wire an observer or a scheduled files:prune-style command; otherwise storage grows unbounded and nobody notices for a year.
• Extension points to look for: a custom disk resolver, a FileManager facade/contract binding for swapping implementations, and events around upload/delete if you need to hook audit logging. Prefer these over editing published views or vendored code — published views are yours to break on the next publish, and vendored edits are lost on upgrade.
• Upgrade procedure for the next minor: read the compare diff, run the test suite against Storage::fake, and diff any republished config file against yours before overwriting.