Easyadmin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require easycorp/easyadmin-bundle
   

   Ensure your project uses Symfony 5.4+ and PHP 8.0.2+.

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

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

3. Create a CRUD Controller: Generate a basic CRUD controller for an entity (e.g., Product):

   php bin/console make:crud Product
   

   This auto-generates a controller extending AbstractCrudController.

4. Register the Controller: Add the route to config/routes.yaml:

   easy_admin:
       resource: '@EasyAdminBundle/Controller/EasyAdminController.php'
       type: 'annotation'
       prefix: '/admin'
   

5. Access the Admin Panel: Visit /admin in your browser. The bundle auto-detects entities with Doctrine annotations (e.g., @ORM\Entity).

First Use Case: Quick Entity Management

• List/Edit/Delete Entities: EasyAdmin provides a pre-built UI for CRUD operations.
• Customize Fields: Override the configureFields() method in your CRUD controller to show/hide fields:

  public function configureFields(string $pageName): iterable
  {
      return [
          'id',
          'name',
          'price',
          'createdAt' => ['type' => 'datetime'],
      ];
  }
  

Implementation Patterns

Core Workflows

1. Entity Configuration:

   • Use YAML/Annotation/XML to define entity metadata (e.g., @EasyAdmin\Config).
   • Example with annotations:

     use EasyCorp\Bundle\EasyAdminBundle\Config\Type;
     
     /**
      * @EasyAdmin\Config(
      *     type=Type::EDIT,
      *     items={
      *         "name",
      *         "price" => ["type" => Type::NUMBER]
      *     }
      * )
      */
     class Product {}
     

2. Customizing the Admin UI:

   • Templates: Override Twig templates in templates/EasyAdminBundle/crud/ (e.g., list.html.twig).
   • Styles: Extend the SCSS variables in assets/EasyAdminBundle/scss/_variables.scss.

3. Advanced CRUD:

   • Actions: Add custom buttons (e.g., bulk actions):

     public function configureActions(Actions $actions): Actions
     {
         return $actions
             ->add(Crud::PAGE_INDEX, Action::DETAIL)
             ->add(Crud::PAGE_INDEX, Action::EDIT)
             ->add(Crud::PAGE_INDEX, Action::DELETE);
     }
     

   • Filters: Enable filtering in configureFields():

     'name' => ['type' => 'string', 'filterable' => true],
     

4. Integration with Forms:

   • Use EasyAdmin\Field\AssociationField for relationships:

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

Integration Tips

• Doctrine Extensions: Works seamlessly with StoDoctrineExtensions (e.g., Sluggable, Sortable).
• API Integration: Use EasyAdmin\Router\AdminUrlGenerator to generate admin URLs in API responses.
• Security: Restrict access via Symfony’s security system (e.g., ROLE_ADMIN):

  # config/packages/security.yaml
  access_control:
      - { path: ^/admin, roles: ROLE_ADMIN }
  

Gotchas and Tips

Common Pitfalls

1. Entity Auto-Detection:

   • EasyAdmin only auto-detects entities with @ORM\Entity. Explicitly register others in configureEntities():

     public function configureEntities(EntityManager $entityManager): iterable
     {
         yield Product::class;
         yield Category::class;
     }
     

2. Field Type Mismatches:

   • Ensure field types match Doctrine types (e.g., Type::TEXT for string, Type::NUMBER for float).
   • Debug with dd($entity) in a custom action to verify data structure.

3. Caching Issues:

   • Clear cache after changes:

     php bin/console cache:clear
     

   • Disable caching in config/packages/easy_admin.yaml for development:

     easy_admin:
         design:
             assets:
                 cache: false
     

4. Permission Denied:

   • Verify ROLE_ADMIN or custom roles are assigned to users. Check Symfony’s profiler (/_profiler) for errors.

Debugging Tips

• Enable Debug Mode:

  # config/packages/dev/easy_admin.yaml
  easy_admin:
      design:
          template:
              layout: 'EasyAdminBundle:layout.html.twig'
  

• Log Entities: Add this to a CRUD controller to log entity data:

  public function __invoke(Request $request): Response
  {
      $entity = $this->entityManager->getRepository($this->entityClass)->find(1);
      \Log::debug('Entity data:', ['entity' => $entity]);
      // ...
  }
  

Extension Points

1. Custom Field Types: Create a new field type by extending EasyAdmin\Field\FieldInterface:

   class CustomField extends AbstractField
   {
       public static function new(): self
       {
           return new self();
       }
   
       public function renderCell(Field $field, $entityValue, Entity $entity): string
       {
           return '<span class="custom-style">' . $entityValue . '</span>';
       }
   }
   

2. Event Listeners: Hook into lifecycle events (e.g., prePersist):

   // src/EventListener/ProductListener.php
   class ProductListener implements EventSubscriber
   {
       public static function getSubscribedEvents()
       {
           return [
               Crud::ENTITY_PERSIST => 'onPersist',
           ];
       }
   
       public function onPersist(BeforeCrudEvent $event): void
       {
           $entity = $event->getEntity();
           $entity->setSlug(Str::slug($entity->getName()));
       }
   }
   

3. API Mode: Enable API-only mode for headless admin:

   easy_admin:
       design:
           assets:
               extra_javascript: []
               extra_stylesheets: []
   

Pro Tips

• Bulk Actions: Use EasyAdmin\Action\Action for custom bulk operations:

  $actions->add(Crud::PAGE_INDEX, Action::NEW, 'New')
      ->linkToCrudAction('new');
  

• Soft Deletes: Integrate with gedmo/doctrine-extensions for soft deletes:

  use Gedmo\Mapping\Annotation as Gedmo;
  
  /**
   * @Gedmo\SoftDeleteable(fieldName="deletedAt")
   */
  class Product {}
  

• Performance: Disable unused features (e.g., search, filters) in configureFields() to reduce load time.