Elorest Laravel Package

Getting Started

This package is a file-upload utility for Laravel that handles receiving an uploaded file, generating a stored filename, and placing it on a configured filesystem disk. Version 1.32.2 is a patch release that corrects the generated filename during upload, so it is a safe drop-in upgrade from other 1.32.x releases.

First steps:

1. Install with composer require at ^1.32.2 and publish any package config (php artisan vendor:publish) so disk and naming defaults are explicit in your repo.
2. Check config/filesystems.php for the disk you intend to use and confirm php artisan storage:link has been run if uploads are publicly served.
3. Open the package's config file first — filename generation strategy, storage path/prefix, and allowed MIME types are the three settings that drive most day-to-day behaviour.
4. Make your first upload in a controller or form request: validate the file with Laravel's file/mimes/max rules, pass the UploadedFile to the package's upload entry point, and persist the returned path on your model.

The most common first use case is a single "avatar" or "document" field on an Eloquent model: validate, upload, store the returned relative path in a string column, and resolve it through Storage::disk(...)->url($path) when rendering. Treat the package as the naming-and-storage layer only; authorization, validation, and persistence remain yours.

Implementation Patterns

Wrap the upload in a form request. Keep validation rules in a StoreAttachmentRequest, then call the package from the controller. This keeps the storage call out of request lifecycle code and makes the upload testable in isolation.

Centralise disk and path configuration. Rather than passing a disk on every call, set a default disk in the package config (e.g. uploads) and a per-environment override in .env. Pass explicit disks only for exceptional cases such as private documents versus public images.

Model the stored path, not the filename. Store the full relative path returned by the package in a string column. Because 1.32.2 changes how filenames are generated, code that reconstructs a path from an original filename or assumes a specific naming convention is the most likely thing to break.

Custom naming via a callback or config strategy. Most upload packages expose a naming hook (hash, slug, timestamp, UUID, or a closure). Prefer deterministic, collision-resistant strategies for user content and only use original filenames where SEO or download-name fidelity matters — and in that case store the original name separately as a display label.

Service-layer integration. If uploads happen from multiple entry points (API, Nova/Filament admin, console imports), put the package call behind a small FileStorageService with methods like store(UploadedFile $file, string $dir): string. This gives you one place to adjust when the package's naming behaviour changes again.

Queue and cleanup. For large files, upload synchronously but defer image conversion, thumbnails, or virus scanning to a job that receives the stored path. Pair the package with a scheduled command that prunes orphaned files, since deleting a model rarely deletes the underlying object automatically.

Testing pattern. Use Storage::fake('uploads') and UploadedFile::fake()->image(...) in feature tests, then assert with Storage::disk('uploads')->assertExists($path). Assert on the path returned by the package rather than hardcoding an expected filename — this is exactly the assertion that 1.32.2 would otherwise break.

Gotchas and Tips

Filename output changed in 1.32.2. This is the headline risk. If any test, seeder, or downstream process asserts a specific generated filename (regex on extension, expected hash length, sanitised characters), re-run it after upgrading. Existing rows are unaffected — only new uploads get the corrected name — so a mixed dataset is expected and usually fine.

Watch for sanitisation and unicode. Bugs in filename generation typically involve spaces, accented characters, multiple dots, or very long original names. After upgrading, upload a file named with spaces, one with unicode, and one with a double extension (e.g. report.pdf.exe) to confirm the stored name is what you expect and that the extension is preserved correctly.

Collision handling. Confirm whether the strategy overwrites on name collision or appends a suffix. If you use original filenames as the basis, two users uploading invoice.pdf to the same directory is a real scenario; prefer hashed names or ensure the package's collision suffix is enabled.

Disk configuration is the usual culprit for 500s. A missing disk entry, an unwritable storage/app directory, or a local disk being used for publicly served assets produces confusing failures that look like package bugs. Check Storage::disk($name)->put() works directly before debugging the package.

Validation belongs to you. Do not rely on the package to reject dangerous uploads. Enforce mimes, max, and where relevant dimensions in the form request, and consider storing user uploads outside the webroot with controlled delivery.

Extension points to know. Look for a naming resolver/callback binding in the service container, a FileUploaded-style event, and any published config keys for path prefix and max size. These are the supported seams; subclassing internal classes is the fastest route to a painful upgrade.

Pin the version deliberately. At 1.32.x the package is mature enough that patch releases should be low risk, but the filename fix is a behavioural change. Run the upload test suite on upgrade, and if you have snapshot or fixture data containing generated names, regenerate it rather than hand-editing.