File Name Generator Laravel Package

Getting Started

• Install with composer require tourze/file-name-generator:^1.0. Treat 1.0.0 as the first semver-stable release and pin to ^1.0 in Laravel apps.
• Look first at the package README, src/, composer.json, and tests: identify the public generator class/interface, any Laravel service provider, config file, and extension/randomization behavior. If Laravel auto-discovery is not present, bind the generator interface in AppServiceProvider.
• First use case: upload normalization. Take the uploaded file’s client name, generate a safe/collision-resistant name, then store it with Storage::disk(...)->putFileAs(...); keep the original filename in the database for display.
• Smoke-test before wiring into real uploads: generate names for spaces, Unicode, missing extensions, very long names, duplicate names, and path-like input.

Implementation Patterns

• Wrap the package behind a small app service such as App\Services\FileNameService. Controllers and jobs should call your wrapper, not package classes directly, so you can swap/decorate the generator later.
• Upload flow: validate the file first, generate the name at the storage boundary, store on the target disk, then persist both the generated path and original filename metadata.
• Use putFileAs / storeAs when you need the exact generated filename. putFile / store may let Laravel choose names and bypass your generator.
• For queued imports, generate the filename before dispatch or pass a stable idempotency key. Avoid regenerating on retries unless duplicate files are acceptable.
• If the package only sanitizes names, add uniqueness yourself: append a short ULID/hash, or check Storage::disk($disk)->exists($candidate) and retry.
• Keep path prefixes out of the generated name. Let Laravel disk configuration and your own directory structure own paths; generate only the filename.
• Test with Storage::fake() and assert stored path plus database metadata. Include malicious names such as ../, null bytes, Windows reserved names, and double extensions.

Gotchas and Tips

• 1.0.0 release notes only link to the compare view. Before upgrading from 0.0.1, inspect the diff, changelog, and tests for renamed classes, signature changes, or changed extension/randomization behavior. Upgrade in a branch and pin ^1.0.
• Treat client filenames as untrusted input. Filename generation is not a replacement for MIME validation, extension allow-lists, malware scanning, or image re-encoding.
• Watch extension handling: preserve vs lowercase, multi-dot names, empty extensions, and double extensions. Do not let a generated filename alone decide the stored MIME type.
• Collisions are still possible with random/time-based generators. Enforce a unique database column or storage check with retry logic.
• Test filesystem portability: max filename length, case-insensitive disks, Unicode normalization, reserved characters, and S3 key constraints.
• If the package exposes config, run php artisan config:cache after changes in deployed environments, otherwise config edits may not take effect.
• Debug by logging original name, generated name, disk, and final path. Check disk permissions and Storage::fake() assertions before blaming the generator.
• Extension points: bind the package interface to a custom implementation, decorate the default generator, or add a wrapper for tenant-specific prefixes/suffixes.