Laravel Enum Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/laravel-enum
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\LaravelEnum\EnumServiceProvider"
   

2. Define an Enum:

   use Spatie\Enum\Enum;
   
   class UserRole extends Enum
   {
       public const ADMIN = 'admin';
       public const EDITOR = 'editor';
       public const VIEWER = 'viewer';
   }
   

3. First Use Case:

   • Validation: Use in Form Requests:

     use Spatie\Enum\WithEnums;
     
     class StoreUserRoleRequest extends FormRequest
     {
         use WithEnums;
     
         public function rules()
         {
             return [
                 'role' => ['required', 'enum:UserRole'],
             ];
         }
     }
     

   • Database Storage: Use in Eloquent models:

     use Spatie\LaravelEnum\HasEnums;
     
     class User extends Model
     {
         use HasEnums;
     
         protected $enumCasts = [
             'role' => UserRole::class,
         ];
     }
     

Where to Look First

• Enum Definition: app/Enums/ (create this directory).
• Model Casting: Check protected $enumCasts in Eloquent models.
• Validation: Use enum: rule in Form Requests or Controllers.
• API Responses: Leverage toEnum() in API resources.

Implementation Patterns

Usage Patterns

1. Database Storage & Retrieval:

   // Store
   $user = User::create(['role' => UserRole::ADMIN]);
   
   // Retrieve
   $role = $user->role; // Returns UserRole object
   $role->value; // 'admin'
   

2. Validation & Sanitization:

   // Form Request
   $request->validate(['role' => ['required', 'enum:UserRole']]);
   
   // Controller
   $role = UserRole::from($request->role); // Throws exception if invalid
   

3. API Responses:

   // Resource
   public function toArray($request)
   {
       return [
           'role' => $this->role->value, // or $this->role->toString()
       ];
   }
   

4. Dynamic Enum Filtering:

   // Query Builder
   User::whereEnum('role', UserRole::ADMIN)->get();
   

5. Enum in Collections:

   $users = User::all();
   $admins = $users->whereEnum('role', UserRole::ADMIN);
   

Workflows

1. Migration Workflow:

   • Add enum column to migration:

     $table->string('role')->comment('UserRole enum');
     

   • Cast in model (as shown above).

2. Seeding:

   User::create(['role' => UserRole::VIEWER]);
   

3. Testing:

   $this->assertEquals(UserRole::EDITOR, $user->role);
   $this->assertTrue(UserRole::isValid('admin'));
   

Integration Tips

• Laravel Nova: Use Spatie\LaravelEnum\Nova\EnumField for custom fields.
• Laravel Scout: Extend toSearchableArray to include enum values.
• API Resources: Override toArray to return enum values as strings or objects.
• Policy Checks:

  public function canEdit(User $user)
  {
      return $user->role->is(UserRole::ADMIN);
  }
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity:

   • Enum values are case-sensitive by default. Use strtolower or strtoupper if needed:

     public const ADMIN = 'admin';
     // vs
     public const ADMIN = 'Admin';
     

2. Database Collation:

   • Ensure your database column collation matches the enum values (e.g., utf8mb4_unicode_ci).

3. Mass Assignment:

   • Enums are not automatically mass assignable. Whitelist them in $fillable:

     protected $fillable = ['role'];
     

4. Serialization:

   • Enums may not serialize/deserialize correctly in JSON. Use toJson() or fromJson():

     $role = UserRole::fromJson('"admin"');
     

5. Caching:

   • Enum classes are cached by Laravel. Clear config cache if modifying enums:

     php artisan config:clear
     

Debugging

1. Invalid Enum Values:

   • Use Spatie\Enum\Exceptions\InvalidEnumValueException in try-catch blocks:

     try {
         $role = UserRole::from('invalid');
     } catch (InvalidEnumValueException $e) {
         // Handle error
     }
     

2. Database Mismatches:

   • Check for silent failures by enabling strict mode in config:

     'strict' => true, // Throws exception on invalid DB values
     

3. Enum Not Found:

   • Ensure the enum class is autoloaded (check composer dump-autoload).

Tips

1. Reusable Enums:

   • Store enums in a shared directory (e.g., app/Shared/Enums) for multi-project use.

2. Enum Methods:

   • Add custom methods to enums for business logic:

     class UserRole extends Enum
     {
         public function canEdit(): bool
         {
             return $this->is(self::ADMIN) || $this->is(self::EDITOR);
         }
     }
     

3. Localization:

   • Use enums with localization:

     class UserRole extends Enum
     {
         public function label(): string
         {
             return __("roles.{$this->value}");
         }
     }
     

4. Performance:

   • Preload enums in service providers:

     public function boot()
     {
         Enum::macro('allValues', function () {
             return array_values(array_filter(get_class_vars(get_called_class()), 'is_string', ARRAY_FILTER_USE_KEY));
         });
     }
     

5. Testing:

   • Mock enums in tests:

     $this->partialMock(UserRole::class, function ($mock) {
         $mock->shouldReceive('is')->andReturnTrue();
     });
     

6. Config Customization:

   • Override default behavior in config/enum.php:

     'cast_as_string' => false, // Return enum objects instead of strings
     'throw_on_invalid' => true, // Throw exception on invalid values
     

7. Dynamic Enums:

   • Use Spatie\Enum\DynamicEnum for runtime-defined enums (advanced use case).