Enum Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require elao/enum
   

   Ensure your project uses PHP 8.4+ and Symfony 6.4+ (if applicable).

2. First Use Case: Basic Enum Define an enum with traits for extended functionality:

   use Elao\Enum\ReadableEnumInterface;
   use Elao\Enum\ReadableEnumTrait;
   
   #[ReadableEnum(prefix: 'user.role.')]
   enum UserRole: string implements ReadableEnumInterface
   {
       use ReadableEnumTrait;
   
       case ADMIN = 'admin';
       case EDITOR = 'editor';
       case USER = 'user';
   }
   

   • Key: The #[ReadableEnum] attribute enables human-readable string representations (e.g., UserRole::ADMIN->getReadable() returns 'user.role.admin').

3. Where to Look First

   • Documentation: README for trait/attribute reference.
   • Tests: tests/ for real-world usage patterns.
   • Symfony Integration: Check src/Symfony/ for form/validator integrations.

Implementation Patterns

1. Framework Integrations

Symfony Forms

• Use EnumType for form fields:

  use Elao\Enum\Bridge\Symfony\Form\EnumType;
  
  $builder->add('role', EnumType::class, [
      'enum' => UserRole::class,
      'placeholder' => 'Select a role',
  ]);
  

• Tip: Combine with ChoiceType for custom labels:

  'choices' => UserRole::ADMIN->getReadable() => 'Administrator',
  

Validation

• Validate enum values in constraints:

  use Elao\Enum\Bridge\Symfony\Validator\Constraints\Enum;
  
  #[Assert\All([
      new Enum(UserRole::class),
  ])]
  public array $roles;
  

2. Database & Eloquent

• Storing Enums: Use Stringable enums (e.g., Suit: string) for database columns.
• Retrieval: Cast via accessors:

  public function getRoleAttribute(string $value): UserRole
  {
      return UserRole::from($value);
  }
  

• Query Scopes: Filter by enum values:

  public function scopeWithRole(Builder $query, UserRole $role)
  {
      return $query->where('role', $role->value);
  }
  

3. API Responses

• Serialize enums to JSON:

  #[AsArray]
  public function toArray(): array
  {
      return ['role' => $this->role->getReadable()];
  }
  

• Tip: Use #[JsonSerializable] for automatic conversion:

  use Elao\Enum\JsonSerializableEnumInterface;
  
  enum UserRole implements JsonSerializableEnumInterface { ... }
  

4. Localization

• Override readable values per locale:

  #[ReadableEnum(prefix: 'user.role.', translations: [
      'en' => ['ADMIN' => 'Admin'],
      'fr' => ['ADMIN' => 'Administrateur'],
  ])]
  enum UserRole { ... }
  

• Integration: Use Symfony’s translator:

  $this->translator->trans($role->getReadable());
  

5. Testing

• Assert enum values:

  $this->assertEquals('user.role.admin', UserRole::ADMIN->getReadable());
  

• Mock enums in unit tests:

  $mockRole = $this->createMock(UserRole::class);
  $mockRole->method('getReadable')->willReturn('mock.role');
  

Gotchas and Tips

Pitfalls

1. Backward Compatibility

   • Version 3.x drops PHP <8.4 and Symfony <6.4 support. Audit dependencies if upgrading.
   • Migration: Replace #[ReadableEnum] with #[Enum\ReadableEnum] if using namespaced attributes.

2. Attribute Overrides

   • Issue: Custom attributes may conflict with #[ReadableEnum].
   • Fix: Use #[Attribute\Target('CLASS')] explicitly or merge attributes:

     #[ReadableEnum(prefix: 'user.role.')]
     #[SomeCustomAttribute]
     enum UserRole { ... }
     

3. Database Migrations

   • Gotcha: Enums with string backings require TEXT/VARCHAR columns, not ENUM (MySQL).
   • Tip: Use Laravel’s Stringable enums for consistency:

     Schema::table('users', function (Blueprint $table) {
         $table->string('role')->comment('UserRole enum value');
     });
     

4. Caching Readable Values

   • Performance: getReadable() is cached per instance, but translations may not be.
   • Workaround: Preload translations or use a static cache:

     UserRole::ADMIN->getReadable('fr'); // Forces locale reload
     

Debugging Tips

1. Enum Not Found Errors

   • Cause: Missing use statement or incorrect enum class reference.
   • Debug: Verify the enum class is autoloaded:

     composer dump-autoload
     

2. Symfony Form Errors

   • Issue: EnumType fails with "Invalid enum value."
   • Fix: Ensure the enum implements Stringable or use value directly:

     'enum' => UserRole::class,
     'choice_value' => fn(UserRole $role) => $role->value,
     

3. Validation Failures

   • Cause: Enum constraint expects exact matches (case-sensitive).
   • Solution: Normalize input:

     $this->assertThat(strtoupper($input), new Enum(UserRole::class));
     

Extension Points

1. Custom Traits

   • Extend functionality by creating traits:

     trait SortableEnum
     {
         public function getSortValue(): int { return $this->value === 'ADMIN' ? 3 : 1; }
     }
     

   • Usage:

     enum UserRole implements SortableEnum { ... }
     

2. Dynamic Enums

   • Load enum cases from a database or config:

     #[ReadableEnum(dynamic: true)]
     enum DynamicRole: string
     {
         use DynamicEnumTrait;
     
         public static function cases(): array
         {
             return config('roles.available');
         }
     }
     

3. Event Dispatching

   • Trigger events on enum access:

     use Elao\Enum\Event\EnumEvent;
     
     enum UserRole
     {
         public function __toString(): string
         {
             $event = new EnumEvent($this);
             $this->dispatcher->dispatch($event);
             return $this->getReadable();
         }
     }
     

4. API Platform

   • Integrate with API Platform’s metadata:

     # config/packages/api_platform.yaml
     api_platform.metadata.enums:
         UserRole: { openapi_type: string, description: 'User roles' }