Onym Laravel Package

Getting Started

Install the package via Composer and publish its config if you need to override defaults:

composer require blaspsoft/onym
php artisan vendor:publish --tag=onym-config

The first place to look is config/onym.php (or the package’s config file after publishing). It typically exposes default strategies, separators, length limits, and allowed characters. Also inspect the package source under vendor/blaspsoft/onym/src for the strategy classes and the main manager/facade — documentation may be thinner than the code itself.

Your first use case should be upload naming. Instead of trusting $request->file('avatar')->getClientOriginalName(), generate a deterministic, collision-resistant name:

use BlaspSoft\Onym\Facades\Onym;

$filename = Onym::strategy('hash')->generate($file);
// e.g. 9f86d081884c7d65.jpg

$path = $file->storeAs('avatars', $filename, 'public');

If the package exposes a helper or Onym::filename() method, use that in a quick Tinker session to confirm the output format before wiring it into controllers or jobs.

Implementation Patterns

Strategy selection per context. Use different strategies for different file types: hashed names for public uploads, slug-based names for human-readable assets, date-prefixed names for reports or exports, and UUID/random names for temporary or user-private files. Avoid a single global default if your app handles mixed media.

$publicName = Onym::strategy('slug')->from($file->getClientOriginalName())->generate();
$reportName = Onym::strategy('date')->prefix('report')->generate();
$tempName   = Onym::strategy('uuid')->generate();

Wrap filename generation in a small application service. Don’t scatter Onym::... calls across controllers, jobs, and observers. Create an UploadNamingService that returns a filename and optionally a full storage path. This makes it easy to change strategies later and to test naming behaviour independently.

class UploadNamingService
{
    public function forPublicUpload(UploadedFile $file): string
    {
        return Onym::strategy('hash')
            ->extension($file->getClientOriginalExtension())
            ->generate();
    }
}

Use model events or observers for persisted files. If your Document model has a path attribute, generate the filename in a creating observer and store it before the file is moved. Combine this with a temporary upload disk so the final name is only assigned once validation passes.

Integrate with Storage and storeAs. Generate the name first, then pass it to Laravel’s filesystem API. Keep the disk name in config rather than hard-coding public or s3.

$name = $namingService->forPublicUpload($request->file('document'));
$path = $request->file('document')->storeAs('documents', $name, config('filesystems.default'));

Chain strategies when the package supports it. If the package offers a fluent builder, compose readable names with a uniqueness suffix: slug + short random token, or date + hash. Check the source for methods like prefix(), suffix(), extension(), length(), and separator().

Test the generated shape, not the exact value. For random or time-based strategies, assert regex patterns, extension preservation, length limits, and uniqueness across multiple calls. For deterministic strategies, assert exact output.

Use it in seeders, imports, and exports. Day-to-day leverage isn’t only HTTP uploads. Use Onym to name generated CSV exports, seeded fixture files, queued report PDFs, and temporary archives. This keeps filenames consistent across CLI and web contexts.

Gotchas and Tips

• Uniqueness is not guaranteed by every strategy. A slug or date strategy can collide under load. Pair it with a random suffix or hash if the file must be unique. If the package provides a unique() modifier, verify whether it checks the filesystem or only appends randomness.
• Race conditions still exist. Generating a name and then writing the file are separate operations. For high-concurrency uploads, use a hash/UUID strategy or handle FileExistsException with a retry loop.
• Watch extension handling. Some strategies may strip or ignore extensions. Explicitly pass the original extension when the package supports it, and normalise case (.JPG vs .jpg) if your storage layer is case-sensitive.
• Path length and filesystem limits. Long slugs plus long extensions can exceed limits on some filesystems or S3 key constraints. Cap slug length and test with real-world long original filenames.
• Sanitisation is not the same as validation. Onym may remove unsafe characters, but it won’t validate MIME types or file size. Keep Laravel validation rules in place; filename generation is not a security boundary.
• Config caching quirks. After changing config/onym.php, run php artisan config:clear in development. In production, remember that config:cache will freeze defaults, so deploy config changes deliberately.
• Facade vs dependency injection. If the package registers a singleton, injecting the manager is cleaner for testing than using the facade everywhere. Check config/app.php aliases and the service provider.
• Low adoption means fewer examples. With a small star count and a recent release, expect to read the source for edge cases. Search for strategy classes, interfaces, and tests in vendor/blaspsoft/onym. If tests are missing, write your own characterisation tests around the strategies you rely on.
• Extension points. If the package exposes a strategy contract, implement a custom strategy for organisation-specific naming (e.g., tenant ID + document type + sequence). Register it in the config or service provider rather than forking the package.
• Storage disk consistency. The filename strategy shouldn’t assume a local disk. If you use S3 or another remote disk, confirm the generated name is a valid object key and that your storeAs call uses the same disk you validated against.
• Debugging tip. Dump a matrix of outputs in Tinker for the strategies you plan to use: short names, long names, names with spaces, Unicode, multiple dots, and missing extensions. That will surface sanitisation and extension bugs before they hit production.