Files Upload Laravel Package

Getting Started

Install the package with Composer and let Laravel auto-discovery register the service provider:

composer require fynduck/files-upload

Publish any package config if the README instructs it:

php artisan vendor:publish --provider="Fynduck\FilesUpload\FilesUploadServiceProvider"

First place to look is the package README and config/files-upload.php (or similarly named config). Confirm your default disk in config/filesystems.php and the package’s default disk/path settings match your app. Then try the smallest use case: upload a single avatar or document from a controller, validate the request with Laravel’s file|mimes|max rules, pass the UploadedFile to the package’s upload helper/facade, and persist the returned path on a model. After upgrading to 4.2.1, re-test any workflow that replaces an existing file in place, since this release fixes an overwrite defect.

Implementation Patterns

• Single-file upload in a controller: validate first, then call the package’s upload method with the file and target disk/path. Store the returned relative path rather than the full URL so disk changes remain portable.
• Eloquent model integration: if the package provides a trait or attribute cast, add it to the model and define file attributes. Keep file columns in $fillable or handle them explicitly, and use the package’s delete/replace hooks on model update and delete.
• Replace/overwrite workflows: use overwrite mode only where replacement is intentional, such as a user avatar or branded asset. Pin ^4.2.1 and add a regression test that uploads the same filename twice and asserts exactly one file remains.
• Multiple uploads: loop over validated files or use the package’s multi-upload API, store an array/JSON column, and manage ordering separately if presentation order matters.
• Custom naming: configure a naming strategy or closure that includes a UUID/hash. This avoids accidental collisions and makes intended overwrites explicit.
• Disk selection: pass the disk per upload when different asset types belong on different storage backends (local, public, S3). Keep sensitive files on private disks.
• Cleanup and lifecycle: delete replaced files when a model is updated, and delete associated files on model deletion. For soft deletes, decide whether files should remain until force delete; add scheduled cleanup for orphaned files.
• Testing: use Storage::fake() and assert file existence, path, and old-file removal. Specifically test overwrite behavior after the 4.2.1 fix, including rapid successive uploads.

Gotchas and Tips

• Overwrite fix in 4.2.1: the release note “Fix overwrite 4x” indicates a bug where overwriting could happen multiple times or behave inconsistently. Upgrade if you rely on replace-in-place behavior, and test concurrent or repeated uploads. Pin at least ^4.2.1.
• Config caching: after changing package config, run php artisan config:clear. Merged package config can silently retain old values in cached environments.
• Public disk symlink: uploads to the public disk are not web-accessible until php artisan storage:link has been run.
• Filename collisions: default naming may preserve original filenames. Use hashed names unless overwrite is explicitly desired; otherwise users can unintentionally replace files.
• Model events: file cleanup often depends on model events. Bulk updates, DB::table() operations, and force deletes may bypass package hooks, leaving orphaned files.
• Queue workers: uploading inside jobs requires care with UploadedFile serialization. Prefer moving the file to a temporary path before dispatching, or perform the upload before queueing.
• Validation is your responsibility: do not assume the package validates MIME type, size, or extension. Validate with Laravel rules before calling the upload API.
• Debugging: check Storage::disk($disk)->exists($path), inspect package config values with config('files-upload'), and review the package’s events or logs if uploads silently return unexpected paths.
• Extension points: custom naming closures, disk resolvers, and package events are the safest customization points. Avoid editing vendor files; bind your own implementations through the service container where the package supports it.