Enum Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle

   composer require fervo/enum-bundle "^2.0"
   

   (Note: The README mentions fervo/enum-bundle, but the GitHub repo is demoniacdeath/enum-bundle. Verify the correct package name in your project.)

2. Enable the Bundle Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3-):

   return [
       // ...
       Fervo\EnumBundle\FervoEnumBundle::class => ['all' => true],
   ];
   

3. Configure an Enum Define a basic enum in config/packages/fervo_enum.yaml:

   fervo_enum:
       enums:
           App\Entity\Enum\Status:
               doctrine_type: status
               form_type: status
   

4. Create Your First Enum Define an enum class (e.g., src/Entity/Enum/Status.php):

   namespace App\Entity\Enum;
   
   use MyCLabs\Enum\Enum;
   
   class Status extends Enum
   {
       const ACTIVE = 'active';
       const INACTIVE = 'inactive';
   }
   

5. Use in a Doctrine Entity Annotate a field in your entity:

   use App\Entity\Enum\Status;
   use Doctrine\ORM\Mapping as ORM;
   
   /**
    * @ORM\Entity()
    */
   class User
   {
       /**
        * @ORM\Column(type="status")
        */
       private $status;
   }
   

6. Use in a Form Auto-generated form type (FervoEnumBundle\Generated\Form\StatusType) or manually:

   use App\Entity\Enum\Status;
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class UserType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->add('status', EnumType::class, [
               'class' => Status::class,
               'choice_label_prefix' => 'status',
           ]);
       }
   }
   

Implementation Patterns

Workflows

1. Enum-Centric Development

   • Design First: Define enums early in the project lifecycle (e.g., UserRole, OrderStatus). Reuse them across entities, forms, and services.
   • Consistency: Use the same enum class name in Doctrine, forms, and translations (e.g., UserRole → doctrine_type: user_role, form_type: user_role).

2. Doctrine Integration

   • Type Mapping: Configure doctrine_type in fervo_enum.yaml to map enums to database columns (e.g., string, integer).
   • Querying: Use enums in DQL or QueryBuilder:

     $query->andWhere('u.status = :status')
           ->setParameter('status', Status::ACTIVE);
     

3. Form Handling

   • Auto-Generated Types: Leverage auto-generated form types (FervoEnumBundle\Generated\Form\*Type) for DRY forms.
   • Customization: Override auto-generated types by extending them or using EnumType with options:

     ->add('status', EnumType::class, [
         'class' => Status::class,
         'choice_label_prefix' => 'custom_prefix.', // Override translation domain
         'expanded' => true, // Render as checkboxes/radio buttons
     ])
     

4. API/Serialization

   • JMS Serializer: Annotate enum fields with @JMS\Type("status") (where status matches doctrine_type).
   • API Platform: Use #[ApiProperty(enumType: Status::class)] for OpenAPI docs.

5. Validation

   • Constraints: Combine with Symfony’s Choice constraint:

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\Choice(callback: [Status::class, 'getValues'])
      */
     private $status;
     

6. Services/Business Logic

   • Type Safety: Pass enums as method parameters for compile-time safety:

     public function processOrder(Order $order, Status $status) { ... }
     

   • Utility Methods: Add static methods to enums for common operations:

     class Status extends Enum {
         public static function isActive($value) {
             return self::from($value) === self::ACTIVE;
         }
     }
     

Integration Tips

• Translation Management:
  • Group translations by enum (e.g., enums.status.active).
  • Use choice_label_prefix in forms to dynamically prefix keys:

    # translations/messages.en.yaml
    status:
        active: "Active"
        inactive: "Inactive"
    

• Database Migrations:
  • Ensure the doctrine_type column exists before using the enum in entities.
  • For existing tables, add a migration to alter the column type (e.g., string → status).
• Testing:
  • Mock enums in unit tests:

    $this->assertEquals(Status::ACTIVE, Status::from('active'));
    

  • Test form submissions with enum values:

    $form->submit(['status' => 'active']);
    $this->assertEquals(Status::ACTIVE, $form->getData()->getStatus());
    

Gotchas and Tips

Pitfalls

1. Bundle Name Mismatch:

   • The README references fervo/enum-bundle, but the repo is demoniacdeath/enum-bundle. Verify the correct package name in composer.json to avoid autoloading errors.

2. Caching Issues:

   • Auto-generated form types are cached. Clear the cache after adding new enums:

     php bin/console cache:clear
     

   • For development, disable caching in config/packages/dev/fervo_enum.yaml:

     fervo_enum:
         debug: true
     

3. Doctrine Type Conflicts:

   • If doctrine_type clashes with existing Doctrine types (e.g., string), rename it or use a custom type mapping:

     doctrine:
         dql:
             string_functions:
                 ENUM_VALUE: App\Doctrine\EnumValueFunction
     

4. Enum Value Casting:

   • Non-string values (e.g., integers) require castValueIn/castValueOut methods. Forgetting this causes serialization/deserialization errors:

     class Status extends Enum {
         public const SUCCESS = 1;
         public static function castValueIn($value) { return (int)$value; }
     }
     

5. Translation Key Conflicts:

   • Overlapping translation keys (e.g., status.active for two different enums) cause the wrong value to render. Use unique prefixes:

     # For UserStatus
     user_status:
         active: "User Active"
     # For OrderStatus
     order_status:
         active: "Order Active"
     

6. ParamConverter Limitations:

   • The @ParamConverter only works for exact enum value matches. For dynamic values, use a custom converter:

     use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
     use App\Entity\Enum\Status;
     
     /**
      * @ParamConverter("status", converter="enum_converter")
      */
     public function showAction(Status $status) { ... }
     

7. Legacy Database Data:

   • If the database contains raw values (e.g., 1 for Status::ACTIVE), ensure castValueIn handles conversion:

     public static function castValueIn($value) {
         return in_array($value, [1, '1']) ? self::ACTIVE : $value;
     }
     

Debugging Tips

1. Check Generated Form Types:

   • Verify the auto-generated form type exists at: vendor/fervo/enum-bundle/Generated/Form/{EnumClass}Type.php.
   • For debugging, temporarily disable caching (debug: true) to regenerate types.

2. Doctrine Logging:

   • Enable SQL logging to confirm enum values are stored correctly:

     # config/packages/dev/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             logging_format: '%%sql%%'
     

3. Enum Validation:

   • Use Enum::isValid() to check values before saving:

     if (!Status::isValid($value)) {
         throw new \InvalidArgumentException("Invalid status: $value");
     }
     

4. Form Debugging:

   • Dump form data to inspect enum values:

     dump($form->getData()->getStatus()->getValue());
     

Extension Points

1. Custom Doctrine Types:
   • Extend Fervo\EnumBundle\Doctrine\EnumType to support custom behavior (e.g