Easyadmin Fields Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atournayre/easyadmin-fields-bundle
   

   Ensure your Laravel project uses EasyAdminBundle 4.2+ (check composer.json under require).

2. Enable the Bundle Add to config/bundles.php:

   Tournayre\EasyAdminFieldsBundle\TournayreEasyAdminFieldsBundle::class => ['all' => true],
   

3. First Use Case: Enum Field In your EasyAdmin CRUD controller, replace a standard field with the EnumField:

   use Tournayre\EasyAdminFieldsBundle\Field\EnumField;
   
   $this->fields = [
       EnumField::new('status')->setEnumClass(MyEnum::class),
       // ... other fields
   ];
   

Where to Look First

• Bundle Docs: Check the GitHub README for field-specific usage.
• Source Code: Explore src/Field/EnumField.php for implementation details (e.g., how setEnumClass() works).
• EasyAdmin Docs: Refer to EasyAdmin’s field customization for context.

Implementation Patterns

Common Workflows

1. Replacing Default Fields Swap EasyAdmin’s default fields (e.g., TextField, ChoiceField) with EnumField for enums:

   $this->fields = [
       EnumField::new('userRole')->setEnumClass(UserRole::class),
       // Fallback to default if enum is missing
       TextField::new('userRole')->hideOnIndex(),
   ];
   

2. Conditional Field Rendering Use setEnumClass() dynamically based on runtime logic:

   $enumClass = $this->getParameter('app.current_enum');
   $this->fields = [
       EnumField::new('priority')->setEnumClass($enumClass),
   ];
   

3. Integration with Forms Ensure your entity’s enum property is type-hinted (PHP 8.1+):

   class MyEntity {
       public UserRole $status; // Required for EnumField to work
   }
   

Pro Tips

• Chaining Methods: Leverage EasyAdmin’s fluent API:

  EnumField::new('status')
      ->setEnumClass(MyEnum::class)
      ->setLabel('User Status')
      ->onlyOnForms() // Show only in edit/create
  

• Localization: Override enum labels via setTranslationDomain():

  EnumField::new('status')
      ->setEnumClass(MyEnum::class)
      ->setTranslationDomain('messages')
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

   • Error: Class 'Tournayre\EasyAdminFieldsBundle\Field\EnumField' not found
   • Fix: Ensure PHP ≥8.1 and atournayre/helpers is installed (auto-included via require).

2. Missing Enum Class

   • Error: Empty dropdown or runtime error if setEnumClass() is omitted.
   • Fix: Always validate the enum class exists:

     if (!class_exists($enumClass)) {
         throw new \RuntimeException("Enum class {$enumClass} not found.");
     }
     

3. Caching Issues

   • Symptom: Enum values not updating after changes to the enum class.
   • Fix: Clear EasyAdmin’s cache:

     php bin/console cache:clear
     

Debugging

• Check Field Registration: Verify the bundle is loaded in config/bundles.php.
• Log Field Rendering: Temporarily add debug output in EnumField::buildView():

  public function buildView(FieldView $view, FormView $formView, array $options)
  {
      \Log::debug('EnumField rendered for: ' . $view->getProperty());
      // ... rest of the method
  }
  

Extension Points

1. Custom Enum Rendering Extend EnumField to modify how enums are displayed:

   class CustomEnumField extends EnumField {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'template' => '@YourBundle/fields/custom_enum.html.twig',
           ]);
       }
   }
   

2. Add New Fields Fork the bundle and add new fields (e.g., JsonField, DateRangeField) by extending AbstractField.

3. Override Templates Copy vendor/tournayre/easyadmin-fields-bundle/Resources/views/fields/enum.html.twig to your theme and customize:

   {# app/Resources/EasyAdmin/Bundles/TournayreEasyAdminFieldsBundle/views/fields/enum.html.twig #}
   <select {{ block('widget_attributes') }}>
       {% for key, label in enumValues %}
           <option value="{{ key }}">{{ label|trans({}, translationDomain) }}</option>
       {% endfor %}
   </select>