Easyadmin Plus Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cisse/easyadmin-plus-bundle
   

   Ensure EasyCorp/EasyAdminBundle (v2.0+) is already installed.

2. Configure Routes: Replace your existing easy_admin.yaml with:

   # config/routes/easy_admin.yaml
   easy_admin_bundle:
       resource: '@CisseEasyAdminPlusBundle/Controller/AdminController.php'
       prefix: /admin
       type: annotation
   

3. First Use Case: Extend the base AdminController in your custom admin controller:

   // src/Controller/Admin/AdminController.php
   namespace App\Controller\Admin;
   
   use Cisse\EasyAdminPlusBundle\Controller\AdminController as BaseAdminController;
   
   class AdminController extends BaseAdminController
   {
       // Override methods or add custom logic here
   }
   

4. Verify: Clear cache and visit /admin to confirm the bundle loads without errors.

Implementation Patterns

Core Workflows

1. Extending Base Functionality: Override methods in your custom AdminController to modify behavior:

   public function configureMenuItems(): array
   {
       return [
           // Custom menu items or overrides
       ];
   }
   

2. Customizing CRUD Operations: Use EasyAdmin’s built-in CRUD extensions (e.g., CrudController) and inject PlusBundle features:

   // src/Controller/Admin/ProductCrudController.php
   use Cisse\EasyAdminPlusBundle\Crud\Action\CustomAction;
   
   class ProductCrudController extends AbstractCrudController
   {
       public static function getEntityFqcn(): string
       {
           return Product::class;
       }
   
       public function configureActions(Actions $actions): Actions
       {
           return $actions
               ->add(CustomAction::new()->setLabel('Custom Action'));
       }
   }
   

3. Dynamic Route Generation: Leverage PlusBundle’s route helpers for admin-specific URLs:

   $this->generateUrl('admin_app_product_edit', ['id' => $product->getId()]);
   

4. Event Listeners/Subscribers: Integrate Symfony events (e.g., KernelEvents::CONTROLLER) to intercept admin requests:

   // src/EventListener/AdminListener.php
   public function onKernelController(ControllerEvent $event): void
   {
       $controller = $event->getController();
       if ($controller instanceof AdminController) {
           // Modify request/response
       }
   }
   

5. Twig Extensions: Use PlusBundle’s Twig helpers in admin templates:

   {{ easy_admin_plus_bundle|admin_menu_item('dashboard') }}
   

Integration Tips

• Symfony Flex: Ensure autoloading is configured if using custom controllers.
• Asset Management: Override assets/ in AdminController to load custom CSS/JS:

  public function configureAssets(): void
  {
      $this->assets()->addCssTheme('custom_admin_theme');
  }
  

• Security: Extend AdminController::checkAccess() to enforce role-based access:

  protected function checkAccess(string $entityName, string $action = null): void
  {
      if (!$this->isGranted('ROLE_SUPER_ADMIN')) {
          throw $this->createAccessDeniedException();
      }
  }
  

Gotchas and Tips

Pitfalls

1. Route Conflict:

   • Issue: Overriding AdminController without updating routes may cause 404s.
   • Fix: Ensure easy_admin.yaml points to your extended controller:

     resource: '@App\Controller\Admin\AdminController.php'
     

2. Method Override Shadowing:

   • Issue: Naming custom methods similarly to PlusBundle’s protected methods (e.g., configureMenuItems) may lead to unexpected behavior.
   • Fix: Prefix custom methods (e.g., appConfigureMenuItems).

3. Dependency Injection:

   • Issue: PlusBundle may not autowire services correctly if EasyAdminBundle is misconfigured.
   • Fix: Verify easy_admin.yaml includes both bundles:

     imports:
         - { resource: '@EasyAdminBundle/Resources/config/routing/annotation.yaml' }
     

4. Template Inheritance:

   • Issue: Custom Twig templates may not inherit PlusBundle’s base templates.
   • Fix: Extend admin/base.html.twig in your theme:

     {# templates/admin/base.html.twig #}
     {% extends '@CisseEasyAdminPlusBundle/admin/base.html.twig' %}
     

Debugging Tips

• Enable Debug Mode:

  # config/packages/dev/debug.yaml
  framework:
      router:
          debug: true
  

• Log Events: Subscribe to EasyAdminPlusEvents to trace execution:

  public static function getSubscribedEvents(): array
  {
      return [
          EasyAdminPlusEvents::PRE_ADMIN_CONTROLLER => 'onPreAdminController',
      ];
  }
  

Extension Points

1. Custom Actions: Create reusable actions by extending AbstractAction:

   // src/Crud/Action/CustomExportAction.php
   use Cisse\EasyAdminPlusBundle\Crud\Action\AbstractAction;
   
   class CustomExportAction extends AbstractAction
   {
       public function __construct()
       {
           parent::__construct('custom_export', 'Export', 'fas fa-file-export');
       }
   
       public function execute(EntityManagerInterface $em, EntityRepository $repo): Response
       {
           // Custom logic
       }
   }
   

2. Dynamic Menu Items: Use configureMenuItems() to fetch data dynamically:

   public function configureMenuItems(): array
   {
       $items = $this->get('doctrine')->getRepository(Product::class)->findActiveProducts();
       return array_map(fn($item) => [
           'label' => $item->getName(),
           'route' => 'admin_app_product_edit',
           'routeParameters' => ['id' => $item->getId()],
       ], $items);
   }
   

3. Override Templates: Copy templates/ from CisseEasyAdminPlusBundle to templates/admin/ in your project to customize without forks.

4. Configuration Overrides: Use config/packages/easy_admin_plus.yaml to override defaults:

   cisse_easy_admin_plus:
       default_theme: 'dark'
       enable_demo_mode: false