- How do I replace auto-increment IDs with UUIDs in my Laravel Eloquent models?
- Use the `HasBinaryUuids` trait on your model and set `$keyType = 'string'` in the model. The package handles binary storage under the hood for MySQL/PostgreSQL/SQL Server, while SQLite defaults to string storage. No migration changes are needed beyond adding the UUID column.
- Does this package support UUIDv7 (time-sortable UUIDs) or only v1–v5?
- This package currently supports UUID versions 1, 3, 4, and 5 only. UUIDv7 (draft standard) is not included, but you can extend it using the `webpatser/uuid` package’s core generator. For v7, consider evaluating alternatives like `ramsey/uuid` or waiting for future updates.
- What Laravel and PHP versions are required for this package?
- The package requires **Laravel 13+** and **PHP 8.5+**. If you’re using an older version, you’ll need to upgrade or use alternatives like `ramsey/uuid`. The strict versioning ensures compatibility with Laravel’s latest Str helpers and binary UUID optimizations.
- How does binary UUID storage improve performance compared to string UUIDs?
- Binary UUIDs (16 bytes) are **55% smaller** than string UUIDs (36 chars), reducing storage and index size. This improves I/O performance in bulk operations (e.g., event sourcing) and high-cardinality indexes. However, APIs must explicitly cast binary UUIDs to strings for JSON responses.
- Can I use this package with SQL Server’s `uniqueidentifier` type?
- Yes, the package includes dedicated methods like `Str::uuidFromSqlServer()` and `Str::uuidToSqlServer()` to handle byte-order conversion (endianness) between Laravel’s binary storage and SQL Server’s `uniqueidentifier`. This ensures compatibility but adds minor overhead in mixed-database environments.
- How do I validate UUIDs in Laravel forms or API requests?
- Use Laravel’s built-in `Uuid` validator rule, e.g., `'field' => 'required|uuid'`. The package integrates with Laravel’s validation system, supporting both string and binary UUID formats. For custom validation (e.g., version-specific checks), extend the `UuidValidator` class.
- What’s the best way to migrate an existing Laravel app to UUIDs?
- Use the `BinaryUuidMigrations` helper to generate database-agnostic migration files. For large tables, consider batch updates or offline migrations to avoid downtime. The package provides utilities like `Str::fastUuid()` for generating UUIDs during migration without performance penalties.
- Will this package work with SQLite, or should I avoid it?
- SQLite is supported, but **binary UUIDs are not natively compatible**, so the package defaults to string storage. This negates the performance benefits of binary UUIDs. If SQLite is critical, stick to string UUIDs or evaluate alternatives like `ramsey/uuid` for full binary support.
- How do I generate UUIDs in bulk (e.g., for seeding or testing)?
- Use `Str::fastUuid()` for high-performance bulk generation (optimized for Laravel’s Str helpers). For testing, leverage `Str::fakeUuid()` to generate predictable UUIDs. The package avoids blocking calls, making it ideal for seeding or batch operations.
- Are there any alternatives to this package, and when should I choose them?
- Alternatives include `ramsey/uuid` (more flexible, supports v7) and `nesbot/carbon` (for time-based UUIDs). Choose this package if you need **Laravel-native integration, binary storage optimizations, or SQL Server support**. Use `ramsey/uuid` if you require UUIDv7 or broader PHP framework compatibility.