Easyadmin Extension Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alterphp/easyadmin-extension-bundle
   

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

   AlterPHP\EasyAdminExtensionBundle\EasyAdminExtensionBundle::class => ['all' => true],
   

3. Update Routes: Replace easy_admin.yaml routes with:

   easy_admin_bundle:
       resource: '@EasyAdminExtensionBundle/Controller/EasyAdminController.php'
       type: annotation
       prefix: /admin
   

First Use Case: List Filters

Configure filters for an entity (e.g., Animation) in config/packages/easy_admin.yaml:

easy_admin:
    entities:
        Animation:
            class: App\Entity\Animation
            list:
                form_filters:
                    - enabled
                    - { property: type, type_options: { choices: { Challenge: 'challenge', Event: 'event' } } }

Result: A filter form appears above the list view.

Implementation Patterns

1. List Filters & Dynamic Filtering

• Static Filters: Use form_filters for predefined filters (e.g., boolean, enum, or related entities).

  list:
      form_filters:
          - { property: status, type_options: { choices_static_callback: [getValuesList, [status]] } }
  

• Dynamic Filters: Append ext_filters to URLs for runtime filtering:

  /admin?action=list&entity=Book&ext_filters[entity.releaseDate]=2016
  

  Note: Chaining filters requires array syntax:

  ext_filters[entity.releaseDate][]=2015&ext_filters[entity.releaseDate][]=2016
  

2. Embedded Lists in Forms/Show Views

• Edit/New Forms: Use type: embedded_list with auto-guessed options:

  form:
      fields:
          - { property: events, type: embedded_list }  # Auto-guesses `entity: Event`
  

• Show Views: Leverage type: embedded_list with template_options:

  show:
      fields:
          - { property: events, type: embedded_list, template_options: { max_results: 5 } }
  

  Tip: Use parent_entity_fqcn/parent_entity_property for custom filters.

3. Autocomplete with "Create" Option

Enable creation of related entities via autocomplete:

form:
    fields:
        - { property: promoter, type: easyadmin_autocomplete, type_options: { attr: { create: true } } }

4. Role-Based Permissions

• Global Minimum Role:

  easy_admin_extension:
      minimum_role: ROLE_ADMIN
  

• Per-Entity Actions:

  entities:
      Product:
          list:
              role: ROLE_ADMIN_PRODUCT_LIST
          new:
              role: ROLE_ADMIN_PRODUCT_NEW
  

5. Custom Form Types

Alias form types for cleaner YAML:

easy_admin_extension:
    custom_form_types:
        enum: App\Form\Type\EnumType

Usage:

form:
    fields:
        - { property: status, type: enum }

Gotchas and Tips

Pitfalls

1. BC Break in ext_filters:

   • The bundle uses ext_filters (not filters) to avoid conflicts with EasyAdmin’s native dynamic filters.
   • Fix: Update all URLs/configs using filters to ext_filters.

2. Embedded List Guesser Limitations:

   • The EmbeddedListHelper may fail for non-ORM fields (e.g., computed properties).
   • Workaround: Manually specify entity_fqcn or parent_entity_property.

3. Role Inheritance:

   • Permissions are not inherited from parent roles. Explicitly define roles for each action.

4. Template Overrides:

   • Customizing embedded list templates requires extending the bundle’s base templates (e.g., EasyAdminExtensionBundle:crud/embedded_list.html.twig).

Debugging Tips

• Filter Debugging:

  • Check ext_filters in the URL or Symfony’s Request object to verify dynamic filters.
  • Use dump($this->get('easyadmin.extension.list_filter_manager')->getFilters()) in a controller to inspect active filters.

• Embedded List Issues:

  • Ensure the related entity’s list configuration exists in easy_admin.yaml.
  • Verify parent_entity_fqcn matches the actual entity class (case-sensitive).

• Permission Denied:

  • Clear cache (php bin/console cache:clear) after updating roles.
  • Check Symfony’s profiler for ACL errors.

Extension Points

1. Custom Filter Operators: Extend AlterPHP\EasyAdminExtensionBundle\Model\ListFilter to add operators like between:

   const OPERATOR_BETWEEN = 'between';
   

2. Override Templates: Copy templates/crud/ from the bundle to templates/EasyAdminExtensionBundle/crud/ to customize embedded lists or modals.

3. Event Listeners: Subscribe to easyadmin.extension.embedded_list.build to modify embedded list queries dynamically:

   // src/EventListener/EmbeddedListListener.php
   public function onBuildEmbeddedList(EmbeddedListEvent $event) {
       $event->getQueryBuilder()->andWhere('e.status = :status')->setParameter('status', 'published');
   }
   

   Register in services.yaml:

   services:
       App\EventListener\EmbeddedListListener:
           tags:
               - { name: kernel.event_listener, event: easyadmin.extension.embedded_list.build, method: onBuildEmbeddedList }
   

4. Form Type Extensions: Extend AlterPHP\EasyAdminExtensionBundle\Form\Type\EmbeddedListType to add custom options or validation.

Performance Quirks

• Large Embedded Lists: Limit results with max_results or lazy-load via template_options: { pagination: { items_per_page: 10 } }.
• Filter Performance: Avoid complex choices_static_callback for large datasets; pre-compute values in the entity’s static method.

Configuration Validation

• Use Symfony’s validator to validate easy_admin.yaml:

  # config/packages/validator.yaml
  services:
      App\Validator\Constraints\EasyAdminConfig:
          tags: [validator.constraint_validator]
  

  Example Constraint:

  public function validate($value, Constraint $constraint) {
      if (!isset($value['entities']['Product']['list']['form_filters'])) {
          $this->context->buildViolation('Missing form_filters for Product')
               ->atPath('[entities][Product][list]')
               ->addViolation();
      }
  }