Easyadmin Plus Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 2lenet/easyadmin-plus-bundle
   

   Ensure EasyAdminBundle (v1.17+) is also installed.

2. Configure Routes Replace your easy_admin.yaml with:

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

3. First Use Case: Auto-Generated CRUD Create a Doctrine entity (e.g., src/Entity/Product.php) with annotations/asserts. Run the generator to scaffold admin config:

   php bin/console lle:easyadmin:generate Product
   

   This creates a YAML config file (e.g., config/easyadmin/products.yaml) with:

   • Default fields (based on Doctrine types/asserts).
   • ACL rules (if configured).
   • Workflow states (if defined in entity).

4. Verify Access /admin to see the auto-generated admin panel with:

   • List view with filters.
   • Batch actions (e.g., CSV export).
   • Translation management (if translatable bundle is used).

Implementation Patterns

1. Auto-Configuration Workflow

• Generator Command: Use lle:easyadmin:generate to auto-generate admin configs for entities. Example:

  php bin/console lle:easyadmin:generate User --fields="name,email,roles" --acl="ROLE_ADMIN:create,edit"
  

  • Flags: --fields: Override auto-detected fields. --acl: Define role-based permissions (e.g., ROLE_USER:view). --workflow: Enable workflow states (e.g., draft,published).

• Post-Generation: Extend the generated YAML to customize:

  # config/easyadmin/users.yaml
  design:
      group: Users
      tabs:
          - { label: 'Profile', icon: 'user' }
          - { label: 'Permissions', icon: 'lock' }
  

2. ACL Integration

• Define Permissions: Annotate entities with #[ACL] or use YAML:

  # config/easyadmin/products.yaml
  acl:
      ROLE_SUPER_ADMIN: [create, edit, delete]
      ROLE_STORE_MANAGER: [view, edit]
  

• Runtime Checks: The bundle auto-validates permissions on actions (e.g., edit, delete). Override in a custom controller if needed:

  public function isGranted(string $action, $entity): bool
  {
      return parent::isGranted($action, $entity) || $this->customLogic();
  }
  

3. Batch Actions & Exports

• CSV Export: Add to your entity config:

  actions:
      csv_export:
          label: 'Export to CSV'
          icon: 'file-csv'
  

  Trigger via the UI or programmatically:

  $this->get('lle_easyadmin_plus.batch_action_handler')->handle(
      'csv_export',
      $this->getEntityClass(),
      $this->getCurrentFilter()
  );
  

• Custom Batch Actions: Extend the BatchActionHandler service:

  // src/Service/CustomBatchAction.php
  class CustomBatchAction extends AbstractBatchAction
  {
      public function execute(array $entities): void
      {
          // Custom logic (e.g., send emails)
      }
  }
  

  Register in services.yaml:

  Lle\EasyAdminPlusBundle\Service\BatchActionHandler:
      arguments:
          - ['@custom_batch_action']
  

4. Nested Trees & Workflows

• Nested Trees: Enable for tree entities (e.g., Category):

  # config/easyadmin/categories.yaml
  design:
      tree:
          property: parent
  

  Use the lle:easyadmin:generate --tree flag to auto-configure.

• Workflows: Define states in your entity (e.g., Draft, Published) and map them in the config:

  workflow:
      states:
          draft: { label: 'Draft' }
          published: { label: 'Published' }
      transitions:
          publish: { from: draft, to: published }
  

  The bundle auto-renders a dropdown for state transitions.

5. Query Builder Customization

• Override Default Queries: Extend the QueryBuilder in your entity config:

  query_builder:
      method: customQueryBuilder
  

  Define the method in a custom AdminController:

  protected function customQueryBuilder(EntityManagerInterface $em, string $entityClass): QueryBuilder
  {
      $qb = $em->getRepository($entityClass)->createQueryBuilder('e');
      $qb->andWhere('e.isActive = :active')->setParameter('active', true);
      return $qb;
  }
  

6. Translation Management

• Auto-Detect Translatable Fields: If using gedmo/doctrine-extensions, the generator auto-configures translation tabs:

  design:
      tabs:
          - { label: 'Translations', icon: 'language' }
  

• Manual Override:

  translations:
      fields:
          - { property: 'name', locales: ['en', 'fr'] }
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning: The bundle is deprecated in favor of CruditBundle. Migrate if starting a new project.

2. Generator Overwrites: Running lle:easyadmin:generate on an existing config overwrites it. Backup or use --dry-run first:

   php bin/console lle:easyadmin:generate User --dry-run
   

3. ACL Caching: ACL rules are cached. Clear cache after changes:

   php bin/console cache:clear
   

4. Nested Tree Performance: Deeply nested trees may cause slow queries. Optimize with:

   query_builder:
       method: optimizedTreeQuery
   

   And implement a custom QueryBuilder method.

5. Batch Action Conflicts: Custom batch actions may conflict with default ones. Use unique names:

   actions:
       custom_export:
           label: 'Custom Export'
           handler: '@custom_batch_action'
   

Debugging

1. Generator Issues: Check Doctrine metadata for errors:

   php bin/console doctrine:schema:validate
   

   Enable debug mode in the generator:

   php bin/console lle:easyadmin:generate User -vvv
   

2. ACL Denials: Enable Symfony’s security debug toolbar to inspect denied actions. Log ACL checks:

   # config/packages/security.yaml
   Lle\EasyAdminPlusBundle\Security\AccessDecisionManager:
       arguments:
           - '@logger'
   

3. Workflow State Errors: Ensure entity states match the config. Validate with:

   php bin/console debug:workflow Product
   

Configuration Quirks

1. Field Overrides: To exclude auto-generated fields, use null in the config:

   fields:
       - { property: 'password', type: 'password', type_options: { enabled: false } }
   

2. Dynamic ACLs: Use a service for dynamic permissions:

   acl:
       service: 'lle_easyadmin_plus.acl.dynamic'
   

   Implement DynamicAclProviderInterface.

3. CSV Export Customization: Override the default exporter:

   csv_export:
       exporter: '@custom_csv_exporter'
   

   Define the service to implement CsvExporterInterface.

Extension Points

1. Custom Admin Controllers: Extend LleEasyAdminPlusBundle\Controller\AdminController to add logic:

   class CustomAdminController extends AbstractAdminController
   {
       protected function configureFields(string $entityClass): iterable
       {
           yield from parent::configureFields($entityClass);
           // Add custom fields
       }
   }
   

2. Event Listeners: Subscribe to bundle events (e.g., lle_easyadmin_plus.pre_generate):

   // src/EventListener/CustomGeneratorListener.php
   class CustomGeneratorListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               LleEasyAdminPlusEvents::PRE_GENERATE => 'onPreGenerate',
           ];
       }
   
       public function onPreGenerate(GenerateEvent $event): void
       {
           $event->setConfig(['custom' => 'value']);
       }