Easy Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beastphp/easy-admin-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Beast\EasyAdminBundle\EasyAdminBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Create a minimal config/packages/easy_admin.yaml:

   easy_admin:
       design:
           menu:
               - { label: 'Dashboard', icon: 'dashboard', route: 'easyadmin.dashboard' }
               - { label: 'Users', icon: 'users', route: 'easyadmin.user.crud' }
   

3. First CRUD Controller Generate a CRUD controller for an entity (e.g., User):

   php bin/console make:easyadmin:crud User
   

   This creates a controller at src/Controller/Admin/UserCrudController.php.

4. Access the Admin Panel Visit /admin (or your configured route) and log in with a user having the ROLE_ADMIN role.

Key Files to Review

• config/packages/easy_admin.yaml: Central configuration for routes, design, and ACL.
• src/Controller/Admin/: Auto-generated CRUD controllers for entities.
• templates/admin/: Override default templates (e.g., layout.html.twig).
• config/routes/easy_admin.yaml: Custom route definitions.

First Use Case: List and Edit Users

1. Define a CRUD Controller (auto-generated):

   namespace App\Controller\Admin;
   
   use Beast\EasyAdminBundle\Controller\AbstractCrudController;
   use App\Entity\User;
   
   class UserCrudController extends AbstractCrudController
   {
       public static function getEntityFqcn(): string
       {
           return User::class;
       }
   
       public function configureFields(string $pageName): iterable
       {
           return [
               'id',
               'email',
               'roles',
               'createdAt',
           ];
       }
   }
   

2. Access the Admin Panel:
   • Navigate to /admin/user to list users.
   • Click "Edit" to modify a user’s roles or email.

Implementation Patterns

Workflows

1. Entity CRUD with Minimal Boilerplate

• Pattern: Extend AbstractCrudController for each entity.
• Example:

  class ProductCrudController extends AbstractCrudController
  {
      public static function getEntityFqcn(): string { return Product::class; }
  
      public function configureFields(string $pageName): iterable
      {
          return [
              'name',
              'price',
              'stock',
              'createdAt' => ['label' => 'Published On'],
          ];
      }
  }
  

• Tip: Use make:easyadmin:crud to scaffold the controller.

2. Customizing List Views

• Pattern: Override configureListFields() to control displayed columns.
• Example:

  public function configureListFields(string $pageName): iterable
  {
      return [
          'name',
          'price' => ['format' => 'currency'],
          'stock' => [
              'label' => 'In Stock',
              'format' => function ($stock) {
                  return $stock > 0 ? '<span class="text-success">Yes</span>' : '<span class="text-danger">No</span>';
              },
          ],
      ];
  }
  

3. Form Customization

• Pattern: Use configureFormFields() to add/remove fields or apply validation.
• Example:

  public function configureFormFields(string $pageName): iterable
  {
      return [
          'name',
          'price' => [
              'type' => 'money',
              'currency' => 'EUR',
          ],
          'description' => [
              'type' => 'textarea',
              'attr' => ['rows' => 4],
          ],
      ];
  }
  

4. Action Buttons

• Pattern: Add custom actions (e.g., bulk delete, export).
• Example:

  public function configureActions(): iterable
  {
      return [
          'delete',
          'export' => [
              'label' => 'Export to CSV',
              'icon' => 'file-export',
              'action' => 'export',
          ],
      ];
  }
  

5. Access Control (ACL)

• Pattern: Restrict access via roles in configureMenuItems() or isAccessible().
• Example:

  # config/packages/easy_admin.yaml
  easy_admin:
      design:
          menu:
              - { label: 'Users', icon: 'users', route: 'easyadmin.user.crud', role: 'ROLE_SUPER_ADMIN' }
  

• Dynamic Check:

  public function isAccessible(): bool
  {
      return $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN');
  }
  

Integration Tips

1. Symfony Forms Integration

• Use Symfony’s form types (e.g., ChoiceType, EntityType) in configureFormFields():

  'category' => [
      'type' => 'entity',
      'class' => Category::class,
      'choice_label' => 'name',
  ],
  

2. Doctrine Extensions

• Support soft-deletes or timestamps via Doctrine behaviors:

  #[ORM\Table(name: 'products')]
  #[SoftDelete]
  class Product {}
  

• EasyAdmin auto-detects SoftDeleteable traits.

3. Translation

• Translate labels/placeholders in configureFields():

  'name' => ['label' => 'admin.product.name'],
  

• Load translations in config/packages/easy_admin.yaml:

  easy_admin:
      design:
          translations: ['en', 'fr']
  

4. Event Listeners

• Listen to CRUD events (e.g., prePersist, postRemove):

  // src/EventListener/ProductListener.php
  public function onPrePersist(Product $product)
  {
      $product->setSlug(Str::slug($product->getName()));
  }
  

• Register in services.yaml:

  services:
      App\EventListener\ProductListener:
          tags:
              - { name: kernel.event_listener, event: easyadmin.crud.pre_persist, method: onPrePersist }
  

5. Custom Templates

• Override Twig templates in templates/admin/ (e.g., crud/index.html.twig).
• Extend base templates by copying from vendor/beast/easy-admin-bundle/Resources/views/.

Gotchas and Tips

Pitfalls

1. Outdated Symfony Version

   • Issue: The bundle targets Symfony 4.1. Use a wrapper or fork if on Symfony 5+/6+.
   • Workaround: Check compatibility with symfony/flex or manually patch dependencies.

2. Missing ACL Configuration

   • Issue: Unauthorized users may access admin routes if roles aren’t set.
   • Fix: Always define roles in configureMenuItems() or use Symfony’s security voter.

3. Entity Changes Not Reflected

   • Issue: After altering an entity (e.g., adding a field), the CRUD controller may not update.
   • Fix: Regenerate the controller with make:easyadmin:crud or manually update configureFields().

4. Template Overrides Not Loading

   • Issue: Custom templates in templates/admin/ are ignored.
   • Fix: Ensure the template path matches the bundle’s structure (e.g., crud/show.html.twig for the show action).

5. Doctrine Events Conflicts

   • Issue: Custom Doctrine listeners may interfere with EasyAdmin’s ORM operations.
   • Fix: Use easyadmin.crud.* events instead of generic prePersist/postRemove.

Debugging Tips

1. Enable Debug Mode

   # config/packages/dev/easy_admin.yaml
   easy_admin:
       debug: true
   

   • Logs CRUD operations and template paths to var/log/dev.log.

2. Check Route Generation

   • Dump routes to verify CRUD endpoints:

     php bin/console debug:router | grep easyadmin
     

3. Inspect Controller Logic

   • Override methods like configureFields() and add dump() calls for debugging:

     public function configureFields(string $pageName): iterable
     {
         dump($pageName); // Debug current page (index/edit/show)
         return [...];
     }
     

4. Clear Cache

   • After configuration changes:

     php bin/console cache:clear
     

Configuration