Weave Code
Type-safe enumerator toolkit for Laravel 13+ with attributes, state machines, bitmasks, translations, validation, casts, blade components, and Filament/Livewire/Nova/Inertia integrations.
Frequently asked questions about Enumerator
- How do I migrate from Spatie’s enums to laranail/enumerator in Laravel 13+?
- Use the included Rector migration codemods to automate conversion of Spatie enums to native PHP 8.3+ enums with `laranail/enumerator` attributes. Start with a single model, test validation and database persistence, then gradually replace others. The package provides backward-compatible casts for existing integer columns during transition.
- Can I use state machines with enums in Laravel 13 without complex setup?
- Yes, the package simplifies state machines via the `HasStateMachine` trait. Define transitions (e.g., `OrderStatus::PENDING->APPROVED`) and enforce workflows declaratively. Works seamlessly with Eloquent models and Blade/Livewire forms. Start with a single workflow to validate before scaling.
- Will this work with Laravel 12 or PHP 8.2? Any polyfills?
- No, `laranail/enumerator` requires PHP 8.3+ and Laravel 13+ due to native enum features and Laravel’s attribute system. For legacy stacks, consider Spatie’s enums or upgrade incrementally. The package’s modular design lets you adopt only basic features (labels/validation) first if needed.
- How do I integrate enums with Filament admin panels?
- Use the built-in `FilamentEnumField` and `FilamentEnumTableColumn` components. The package auto-configures dropdowns, badges, and validation for enums in Filament forms and tables. Example: Replace a text column with `FilamentEnumTableColumn::make('status')` for type-safe rendering and filtering.
- Are there performance concerns with dynamic enums or per-tenant overrides?
- Dynamic enums (e.g., tenant-specific values) add minimal overhead via lazy loading. Cache enum metadata globally with `Enum::cache()` for high-traffic apps. Test with your database (MySQL/PostgreSQL) and tenant isolation strategy—most overhead comes from query complexity, not the package itself.
- How do I validate enums in API requests (e.g., GraphQL or JSON:API)?
- Use the `EnumRule` validation class or Laravel’s built-in `in:` rule with the enum’s name (e.g., `Rule::in(UserRole::class)`). For GraphQL, the optional module provides schema validation. For JSON:API, cast enums to strings in your resource classes (e.g., `Attribute::make('role')->castWith(UserRole::class)`).
- Can I use bitmasks for permissions (e.g., role-based access) without bloating my database?
- Yes, bitmasks are stored as integers in the database (e.g., `UserPermission::READ | UserPermission::WRITE`). The package handles serialization/deserialization automatically. Example: `User::find(1)->permissions->has(UserPermission::EDIT)` checks flags without extra queries. Ideal for permission systems with <20 flags.
- How do I test enums with Pest or PHPUnit?
- The Pest module provides `testEnum()` helpers for assertions (e.g., `testEnum(UserStatus::ACTIVE)->isValid()`). For PHPUnit, use `assertContains()` with the enum class or custom matchers. Test edge cases like invalid values, state transitions, and bitmask combinations. Example: `assertTrue(UserRole::ADMIN->has(UserPermission::ALL))`.
- Are there Blade components for rendering enums as dropdowns or badges?
- Yes, include `@enumSelect('status', UserStatus::class)` for dropdowns or `@enumBadge('status')` for inline badges. Customize labels, translations, and attributes via the `enum()` directive. Works with Livewire too—wrap components in `<x-wire:enum-select ... />` for reactive forms.
- What’s the best alternative if I only need simple enums without state machines?
- For basic enums, consider `spatie/laravel-enum` (Laravel 8+) or native PHP 8.1+ enums with manual casts. `laranail/enumerator` adds value if you need state machines, bitmasks, or Filament/Livewire integrations. For minimalism, start with `HasEnumerator` for labels/validation, then add advanced features as needed.
Weaver
How can I help you explore Laravel packages today?