- How do I install and set up the Referenceable package in Laravel?
- Run `composer require eg-mohamed/referenceable` to install, then execute `php artisan referenceable:install` to publish the config and create necessary tables. Add the `HasReference` trait to your Eloquent model and include a `reference` column in your migration.
- What reference formats are supported, and how do I customize them?
- The package supports random, sequential, and template-based formats (e.g., `{YEAR}{MONTH}{SEQ}`). Customize formats in the config file by defining strategies, prefixes, suffixes, and separators. Templates use placeholders like `{RANDOM}`, `{SEQ}`, or `{YEAR}` for dynamic values.
- Does Referenceable work with Laravel 13, or is it limited to older versions?
- Referenceable is fully compatible with Laravel 10–13. The package is regularly updated to ensure compatibility with the latest Laravel releases, including PHP 8.1+ requirements.
- How does the sequential strategy handle collisions or resets (e.g., daily/monthly)?
- Sequential strategies use auto-incrementing counters with configurable reset periods (daily, monthly, yearly). Collisions are prevented via database transactions and retries. The package also supports manual resets via Artisan commands if needed.
- Can I use this package for multi-tenant applications (e.g., SaaS platforms)?
- Yes, Referenceable includes tenant-aware reference generation. It scopes references to the current tenant by default, ensuring uniqueness across all tenants. Configure this in the `tenancy` section of the published config file.
- What happens if a reference format causes a collision (e.g., duplicate random string)?
- The package includes built-in collision handling. If a duplicate is detected, it automatically retries with a modified format (e.g., appending a suffix or regenerating the random string). You can configure the max retries and fallback behavior in the config.
- Are there performance concerns with sequential numbering under high write loads?
- Sequential strategies are optimized for performance with database transactions and caching. For high-write scenarios (e.g., 10K+ records/day), ensure your database has proper indexing on the `reference` column and consider batch processing or read replicas for counters.
- How do I validate or verify a reference number programmatically?
- Use the `validateReference()` method on your model to check if a reference is valid (e.g., matches the expected format). For verification, call `isReferenceValid($reference)` on the model class to check uniqueness and format without instantiating a record.
- Can I regenerate references for existing records without breaking downstream systems?
- Yes, use the `regenerateReference()` method on a model instance to update the reference. For bulk updates, use the `referenceable:regenerate` Artisan command with `--force` to skip validation if needed. Always test in staging first to ensure compatibility with APIs, reports, or external systems.
- What alternatives exist for Laravel reference generation, and why choose Referenceable?
- Alternatives include manual UUIDs, Laravel’s built-in `incrementing` IDs, or packages like `spatie/laravel-activitylog` for audit trails. Referenceable stands out for its flexibility (templates, sequential, random), multi-tenancy support, and built-in collision handling—ideal for user-facing labels like invoices or tickets.