Easy Fields Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require agence-adeliom/easy-fields-bundle
   

   Ensure your composer.json includes the Flex recipe endpoint for seamless integration.

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

   Adeliom\EasyFieldsBundle\AdeliomEasyFieldsBundle::class => ['all' => true],
   

3. First Use Case: Replace a standard AssociationField in your EasyAdmin CRUD controller with Adeliom\EasyFieldsBundle\Admin\Field\AssociationField to enable inline creation of associated entities.

   use Adeliom\EasyFieldsBundle\Admin\Field\AssociationField;
   
   $crud->addField(AssociationField::new('author')
       ->setEntity(Foo::class)
       ->setLabel('Author')
       ->autocomplete()
   );
   

Implementation Patterns

Core Workflows

1. Inline Association Creation: Use AssociationField to create new associated entities directly from the parent entity form.

   $crud->addField(AssociationField::new('posts')
       ->setEntity(Post::class)
       ->setLabel('Related Posts')
       ->allowAdd()
   );
   

2. Autocomplete Integration: Combine with Symfony UX Autocomplete for seamless search:

   $crud->addField(AssociationField::new('user')
       ->setEntity(User::class)
       ->autocomplete()
       ->setAutocompleteRoute('app_user_autocomplete')
   );
   

3. Custom Field Types: Extend existing fields (e.g., TextField) to add custom logic:

   use Adeliom\EasyFieldsBundle\Admin\Field\TextField;
   
   $crud->addField(TextField::new('description')
       ->setLabel('Description')
       ->addCssClass('custom-class')
   );
   

Integration Tips

• Dependency Injection: Inject AdeliomEasyFieldsBundle services (e.g., field_factory) into custom field classes for reusable logic.

  public function __construct(private FieldFactory $fieldFactory) {}
  

• Configuration Overrides: Override default field behavior via config/packages/adeliom_easy_fields.yaml:

  adeliom_easy_fields:
      association:
          default_allow_add: true
  

• Event Listeners: Subscribe to EasyFieldsEvents (e.g., PRE_BUILD_FORM) to modify field behavior dynamically:

  $eventDispatcher->addListener(EasyFieldsEvents::PRE_BUILD_FORM, function (FieldEvent $event) {
      $event->getField()->addCssClass('dynamic-class');
  });
  

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch: Ensure your Symfony version aligns with the bundle’s compatibility table (e.g., 3.x for Symfony 6.4+). Fix: Downgrade/upgrade Symfony or use a supported branch (2.x for 5.4–6.x).

2. Circular References: Inline creation may cause infinite loops if allowAdd() is enabled on mutually dependent entities (e.g., User ↔ Profile). Fix: Use ->setTargetEntity(Foo::class) explicitly and disable allowAdd() on one side.

3. Autocomplete Route Conflicts: Custom autocomplete routes must return JSON with data and label keys. Misconfigured routes break field rendering. Fix: Verify route returns:

   { "data": [{"id": 1, "label": "John Doe"}] }
   

Debugging

• Field Not Rendering: Check if the field is properly registered in the CRUD controller and the entity has the corresponding property. Debug: Use dump($crud->getFields()) to inspect field configurations.

• JavaScript Errors: Clear cache (php bin/console cache:clear) and check browser console for missing assets (e.g., autocomplete JS). Fix: Ensure adeliom_easy_fields assets are enabled in config/packages/twig.yaml:

  twig:
      paths:
          '%adeliom_easy_fields%/templates': AdeliomEasyFieldsTemplates
  

Extension Points

1. Custom Field Types: Create a new field by extending AbstractField and register it via:

   $crud->addField(new CustomField('property'));
   

2. Override Templates: Override bundle templates in templates/admin/fields/:

   {# templates/admin/fields/association.html.twig #}
   <div class="custom-association">
       {{ include('AdeliomEasyFieldsBundle:Field:association.html.twig') }}
   </div>
   

3. Validation: Add custom validation to fields using Symfony’s Constraint system:

   $crud->addField(TextField::new('title')
       ->addConstraint(new UniqueEntity(['entity' => Post::class]))
   );