- How do I generate a UUID in Laravel using this package?
- Use the `Str::uuid()` helper or the `Uuid::generate()` facade to create a v4 UUID. For version-specific UUIDs (e.g., v1 for time-based), call `Uuid::generate(1)`. The package integrates seamlessly with Laravel’s Str helper for consistency.
- Can I use UUIDs as primary keys in Eloquent models?
- Yes. Apply the `HasUuids` trait to your Eloquent model to automatically assign UUIDs as primary keys. For binary storage (recommended for performance), use `HasBinaryUuids` instead, which stores UUIDs as `binary(16)` in the database.
- What Laravel and PHP versions does this package support?
- This package requires **Laravel 13.x** and **PHP 8.5+**. If you’re on Laravel 10/11 or older PHP versions, you’ll need to upgrade your Laravel stack or consider alternatives like `ramsey/uuid` for broader compatibility.
- How do I migrate from auto-increment IDs to UUIDs in an existing Laravel app?
- Start by adding a UUID column (e.g., `uuid` as `binary(16)`) to your tables, then backfill existing records. Use Laravel migrations to alter tables safely. For foreign keys, ensure your relationships reference the UUID column instead of the old auto-increment ID.
- Does this package support SQL Server (GUID) databases?
- Yes, but with caveats. The package includes SQL Server support, but you may need to validate UUID conversion logic (e.g., mixed-endianness handling) in production. Test thoroughly if using mixed-database environments or complex queries involving UUIDs.
- What’s the performance impact of using binary UUIDs vs. string UUIDs?
- Binary UUIDs (stored as `binary(16)`) are **55% smaller** than string UUIDs (e.g., `char(36)`) and faster to compare/index. However, they require serialization/deserialization for APIs (e.g., JSON). The package provides `fastUuid()` macros to optimize UUID generation.
- How do I handle UUIDs in JSON APIs or GraphQL responses?
- By default, Eloquent will serialize binary UUIDs as hex strings. For consistency, cast UUIDs to strings in your API responses using accessors (e.g., `public function getUuidAttribute()`) or Laravel’s `JsonSerializable` interface.
- Is this package actively maintained? What if I encounter issues?
- The last release (v7.0.0) was in 2024, with no recent commits. If you hit issues, consider forking the package (MIT license) or contributing fixes. Alternatives like `ramsey/uuid` or `spatie/laravel-uuid` may offer more active maintenance.
- Can I use UUID versions other than v4 (e.g., v1 for time-based IDs)?
- Yes. The package supports UUID versions 1–8. Use `Uuid::generate(1)` for time-based UUIDs (v1), `Uuid::generate(4)` for random UUIDs (v4), or `Uuid::generate(6)` for hybrid time/random UUIDs. Version 1 is useful for distributed systems requiring temporal ordering.
- How do I ensure UUIDs are unique across distributed Laravel instances?
- UUIDs (especially v4) are designed to be globally unique without coordination. For time-based UUIDs (v1/v6), ensure your servers’ clocks are synchronized. The package’s `HasUuids` trait handles uniqueness automatically in Eloquent, but validate uniqueness constraints in your database schema.