Weave Code
Variable Keys Laravel Package
cline/variable-keys
Laravel Blueprint macros for variable primary key types, matching foreign keys, and polymorphic morph types. Easily switch between id/uuid/ulid (and more) via enums/config to keep migrations consistent across models and relationships.
Laravel Blueprint macros for variable primary key and morph types
Frequently asked questions about Variable Keys
- How do I switch from integer IDs to UUIDs in an existing Laravel app without breaking migrations?
- Use `Schema::table()` to add a UUID column alongside the existing integer key, backfill data, then drop the old column. The package’s `variablePrimaryKey()` macro simplifies the process by handling type-specific syntax. For polymorphic relationships, ensure all related tables use the same `MorphType` enum value (e.g., `MorphType::UUID`). Test thoroughly in staging first, as foreign key constraints may need adjustments.
- Does this package support composite primary keys (e.g., multi-column keys) or only single-column keys?
- Currently, the package focuses on single-column primary keys (e.g., `id`, `uuid`, `ulid`). Composite keys are not natively supported, but you could extend the `Blueprint` macros or use raw SQL for custom composite key logic. The design prioritizes simplicity for the most common use case—variable single-column keys—while leaving room for future expansion.
- Will this work with Laravel 9 or older versions? What’s the minimum PHP requirement?
- The package requires **PHP 8.4+** and is optimized for **Laravel 10+** due to its use of PHP 8.4 features like enums and union types. For older versions, you’d need to polyfill enums or use a fork, but backward compatibility isn’t guaranteed. The Blueprint system in Laravel 10+ provides the best integration for dynamic key-type handling.
- How do I configure the package to use ULIDs instead of UUIDs for time-ordered data?
- Add `ULID` to the `PrimaryKeyType` enum (extend the enum if needed) and update your `config/database.php` to set `'primary_key_type' => 'ulid'`. The package abstracts key generation, so you’ll need to ensure your database supports ULIDs (e.g., PostgreSQL with a `UUID` column type or MySQL with `CHAR(26)`). For ULID generation, integrate a library like `ramsey/ulid` alongside the package.
- Can I mix key types across models (e.g., UUIDs for users, integers for posts) in the same app?
- Yes, the package supports per-model key types by passing the `PrimaryKeyType` enum directly to `variablePrimaryKey()` in each migration. However, polymorphic relationships between models with mismatched key types (e.g., a `Post` with integer ID morphing to a `User` with UUID) will require explicit `morphMap` configuration in Eloquent to resolve the foreign key type correctly.
- What’s the performance impact of using UUIDs vs. auto-increment integers in high-write applications?
- UUIDs (especially random v4) introduce overhead due to generation time and larger storage size (16 bytes vs. 4 bytes for integers). Benchmark your workload: for >10K writes/sec, consider ULIDs (time-ordered) or integer keys. The package abstracts generation, but databases like PostgreSQL optimize UUID indexing better than MySQL/SQLite. Test with your specific DB and query patterns to measure join/constraint impacts.
- How do I handle foreign keys when retrofitting UUIDs to an existing table with integer IDs?
- Use `Schema::table()` to add a UUID column, backfill data with a migration, then drop the old integer column. For foreign keys, use `variableForeignKey()` with the target table’s `PrimaryKeyType`. If the referenced table uses integers, you’ll need to either: 1) convert it to UUIDs, or 2) use a raw `foreignId()` with a custom constraint. Always test rollbacks, as dropping constraints on non-integer keys can fail in some databases.
- Does this package work with third-party packages like Spatie’s Laravel Permissions or Activity Log?
- Most third-party packages assume integer keys, so you may need to extend them or patch their migrations. For example, Spatie’s `activitylog` can be configured to use UUIDs by overriding the `logName()` or `logOnly()` methods. Check the package’s docs for key-type assumptions. The `MorphType` enum helps align polymorphic relationships, but some packages might still require custom model bindings or trait overrides.
- How do I test polymorphic relationships with variable key types across different databases?
- Use Laravel’s database testing utilities to test each key type (e.g., UUID, integer) in isolation. Mock the `MorphType` enum in unit tests to verify resolution logic. For integration tests, spin up containers for PostgreSQL, MySQL, and SQLite to catch DB-specific quirks (e.g., UUID storage formats). Focus on edge cases like orphaned records, key collisions, and foreign key constraint failures.
- What are the alternatives to this package for handling variable primary keys in Laravel?
- Alternatives include: 1) **Manual migrations** with raw SQL for UUID/ULID columns (less maintainable), 2) **Custom traits** to override Eloquent’s `getKey()` and `getIncrementing()`, 3) **Database-specific extensions** (e.g., Laravel’s `uuid` package for PostgreSQL), or 4) **ORM layers** like Doctrine with custom ID types. This package stands out by integrating directly with Laravel’s Blueprint system, reducing boilerplate and ensuring consistency across migrations and relationships.
Weaver
How can I help you explore Laravel packages today?