- How do I generate sequential invoice numbers like INV-0001, INV-0002 in Laravel using this package?
- Use the sequential strategy by configuring your model with `protected $referenceStrategy = 'sequential'`. Set a prefix (e.g., 'INV') and padding (e.g., 4 digits) in the model or config. The package auto-increments the sequence and handles resets (daily/monthly/yearly) via `reset_rule` in the config.
- Can this package handle multi-tenant applications where each tenant needs isolated reference numbers?
- Yes, the package supports multi-tenancy by specifying a `tenant_column` in your model’s reference config. It ensures TenantA gets ORD-001 while TenantB gets ORD-001 independently. Requires proper database indexing for performance. Test with high tenant volumes (e.g., 10K+) to validate scalability.
- What Laravel versions does this package support, and are there breaking changes between versions?
- The package supports Laravel 10–13 with zero breaking changes. Version 2.x maintains backward compatibility with 1.x configs. Run `php artisan referenceable:validate` post-migration to check for deprecated settings. Always update dependencies via Composer for minor version patches.
- How does collision handling work if two records try to generate the same reference (e.g., sequential strategy)?
- By default, the package uses retry logic to resolve collisions. Configure `collision_strategy` in `config/referenceable.php` to either `retry` (default), `fail`, or `append` (e.g., INV-0001 → INV-0001-1). For high-volume systems, test edge cases with concurrent writes to ensure performance.
- Can I use custom templates like {YEAR}/{MONTH}/{SEQ} for references, and how do I validate them?
- Yes, use the template strategy with placeholders like `{YEAR}`, `{MONTH}`, `{SEQ}`, or `{RANDOM}`. Validate templates via the `validateReference()` method before deployment. Example: `protected $referenceTemplate = 'ORD-{YEAR}-{SEQ:04}'` generates ORD-2024-0001. The package throws exceptions for invalid syntax.
- What’s the best way to migrate an existing Laravel app to use this package without downtime?
- Start by auditing models needing references. Add the `reference` column to migrations, then apply the `HasReference` trait incrementally. Use `php artisan referenceable:install` to set up counters. For backfilling existing records, batch-process references with `batch_size` config to avoid DB locks. Test in staging first.
- Does this package work with PostgreSQL, or is it MySQL-only?
- The package supports MySQL, PostgreSQL, and SQLite out of the box. No database-specific hacks are required. Ensure your `reference` column is a string type with a unique index. For PostgreSQL, test sequential strategies under high concurrency to validate auto-increment behavior.
- How can I optimize performance for bulk reference generation (e.g., 10,000+ records)?
- Enable caching with `cache_config: true` in the config and set `batch_size: 100` to reduce DB transactions. For sequential strategies, index the `reference_counters` table. Avoid generating references in loops; use batch inserts or queue jobs for large datasets. Monitor DB locks during bulk operations.
- Are references immutable, or can I regenerate them if a mistake is made (e.g., wrong prefix)?
- References are immutable by default to maintain audit trails. To regenerate, use the `regenerateReference()` method on the model, but note this may violate uniqueness constraints. For corrections, consider adding a `reference_version` column or using soft deletes. Always back up data before mass updates.
- What are the alternatives to this package, and why should I choose Referenceable?
- Alternatives include `laravel-uuid` (for UUIDs) or custom solutions with `DB::raw()`. Referenceable stands out for its **template flexibility**, **multi-tenancy**, **sequential strategies**, and **collision handling**—all in a single package. It’s ideal for human-readable IDs (e.g., invoices) while avoiding the complexity of UUIDs or manual logic.