Easyadmin Extension Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require alterphp/easyadmin-extension-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       AlterPhp\EasyAdminExtensionBundle\AlterPhpEasyAdminExtensionBundle::class => ['all' => true],
   ];
   

2. First Use Case: Customizing CRUD Actions Extend a CRUD controller by overriding the configureActions() method in your entity CRUD class:

   use AlterPhp\EasyAdminExtensionBundle\Extension\Action\ActionExtension;
   
   class PostCrudController extends EasyAdminCrudController
   {
       public static function getEntityFqcn(): string
       {
           return Post::class;
       }
   
       public function configureActions(Actions $actions): Actions
       {
           $actions = parent::configureActions($actions);
           $actions->add(ActionExtension::create('custom_action', 'Custom Action', 'fas fa-rocket')
               ->linkToCrudAction('customAction')
           );
           return $actions;
       }
   
       public function customAction(EntityManagerInterface $em, $id): Response
       {
           // Custom logic
           return $this->redirectTo('index');
       }
   }
   

3. Where to Look First

   • Documentation: Check the README for version compatibility and breaking changes.
   • Extension Classes: Focus on src/Extension/ in the bundle for available extensions (e.g., ActionExtension, FieldExtension).
   • Example Usage: Review the tests/ directory for practical examples of integration.

Implementation Patterns

Common Workflows

1. Extending CRUD Actions

Use ActionExtension to add custom actions (e.g., bulk operations, custom redirects):

$actions->add(ActionExtension::create('export_csv', 'Export CSV')
    ->linkToRoute('app_export_csv', ['entity' => 'post'])
    ->displayIf(fn($entity) => $entity->isExportable())
);

2. Customizing Fields

Override field rendering with FieldExtension:

use AlterPhp\EasyAdminExtensionBundle\Extension\Field\FieldExtension;

public function configureFields(string $pageName, FieldCollection $fields): FieldCollection
{
    $fields = parent::configureFields($pageName, $fields);
    if ($pageName === 'edit') {
        $fields->add(FieldExtension::create('custom_field')
            ->setTemplate('@EasyAdminExtension/custom_field.html.twig')
            ->setLabel('Custom Field')
            ->setFormType(CustomFieldType::class)
        );
    }
    return $fields;
}

3. Menu and Route Extensions

Dynamically modify the menu or routes:

use AlterPhp\EasyAdminExtensionBundle\Extension\Menu\MenuExtension;

public function configureMenuItems(MenuItemCollection $menuItems): MenuItemCollection
{
    $menuItems = parent::configureMenuItems($menuItems);
    $menuItems->addMenuItem(MenuExtension::create('dashboard_custom')
        ->setLabel('Custom Dashboard')
        ->setRoute('app_custom_dashboard')
        ->setPosition(10)
    );
    return $menuItems;
}

4. List Filter Integration

Note: This bundle’s list filters are not compatible with EasyAdmin’s dynamic filters. Use static filters only:

use AlterPhp\EasyAdminExtensionBundle\Extension\Filter\FilterExtension;

public function configureListFilters(ListBuilder $builder): ListBuilder
{
    $builder->addListFilter(
        FilterExtension::create('custom_filter')
            ->setFormType(CustomFilterType::class)
            ->setLabel('Custom Filter')
    );
    return $builder;
}

Integration Tips

1. Dependency Injection Inject the extension services directly into your CRUD controllers:

   public function __construct(
       private ActionExtension $actionExtension,
       private FieldExtension $fieldExtension
   ) {}
   

2. Twig Templates Override default templates by copying them from the bundle’s Resources/views/ to your project’s templates/EasyAdminExtension/.

3. Event Listeners Use Symfony events to dynamically modify behavior:

   // config/services.yaml
   services:
       App\EventListener\EasyAdminExtensionListener:
           tags:
               - { name: kernel.event_listener, event: easyadmin.extension.action, method: onActionExtension }
   

4. Version Compatibility

   • EasyAdmin 2.2.2+: Required for full compatibility.
   • Symfony 4.2+: Minimum version for 3.x branch.
   • Avoid mixing with EasyAdmin’s native dynamic filters (use static filters only).

Gotchas and Tips

Pitfalls

1. Dynamic Filter Conflict

   • Issue: The bundle’s list filters do not work with EasyAdmin’s dynamic filters.
   • Fix: Use static filters only or disable EasyAdmin’s dynamic filters in config/packages/easy_admin.yaml:

     easy_admin:
         design:
             assets:
                 dynamic_filters: false
     

2. Menu Permissions

   • Issue: Versions v2.2.0 and v2.2.1 of EasyAdmin lack native menu permissions, which may cause issues.
   • Fix: Upgrade to >=2.2.2 or manually implement permission checks.

3. Template Overrides

   • Issue: Overriding templates requires copying the entire template hierarchy.
   • Tip: Use debug:container --parameter easyadmin.extension.templates to locate template paths.

4. Action Link Routing

   • Issue: Custom action links may break if routes are not properly configured.
   • Tip: Always test action routes with php bin/console debug:router and use absolute routes when possible.

Debugging

1. Extension Not Loading

   • Verify the bundle is registered in config/bundles.php.
   • Check for PHP version conflicts (e.g., PHP 7.1+ required for 3.x branch).

2. Field/Action Not Rendering

   • Ensure the extension is added after calling parent::configureFields() or parent::configureActions().
   • Clear cache:

     php bin/console cache:clear
     

3. Permission Denied

   • For menu items or actions, explicitly define permissions in security.yaml:

     access_control:
         - { path: ^/admin/custom_action, roles: ROLE_CUSTOM_ACTION }
     

Tips

1. Reusable Extensions Create base CRUD controllers to share common extensions:

   abstract class BaseCrudController extends EasyAdminCrudController
   {
       protected function addCommonExtensions(Actions $actions): Actions
       {
           $actions->add(ActionExtension::create('audit_log', 'View Audit Log'));
           return $actions;
       }
   }
   

2. Conditional Extensions Use closures to conditionally add extensions:

   $actions->addIf(
       fn() => auth()->user()->hasRole('ADMIN'),
       ActionExtension::create('delete_all', 'Delete All')
   );
   

3. Performance

   • Lazy-load heavy extensions (e.g., complex filters) to avoid slowing down the admin panel.
   • Use ->setTemplate() for custom fields to avoid unnecessary database queries.

4. Testing Test extensions in isolation using Symfony’s KernelTestCase:

   public function testCustomAction()
   {
       $client = static::createClient();
       $client->loginUser(self::createAdminUser());
       $crawler = $client->request('GET', '/admin/post/custom_action/1');
       $this->assertResponseIsSuccessful();
   }
   

5. Bundle Updates

   • Monitor for updates to the alterphp/easyadmin-extension-bundle (though inactive, check for forks).
   • Consider forking the repository if critical features are missing.