Easyadmin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require effiana/easyadmin-bundle
   

   Register the bundle in config/bundles.php:

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

2. First Backend Create a CRUD controller for an entity (e.g., Post):

   php bin/console make:crud Post
   

   Configure the route in config/routes.yaml:

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

3. First Use Case Access /admin to see a pre-built admin panel for your Post entity. Customize fields via YAML/annotation in src/Entity/Post.php:

   use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
   use EasyCorp\Bundle\EasyAdminBundle\Config\Field;
   
   #[EasyAdmin\Config]
   class Post
   {
       #[Field]
       public $title;
   
       #[Crud]
       public function configureFields(string $pageName): iterable
       {
           return [
               Field\TextField::new('title'),
               Field\TextareaField::new('content'),
           ];
       }
   }
   

Implementation Patterns

Core Workflows

1. Entity Configuration

   • Use annotations, YAML, or PHP attributes (Symfony 5.8+) to define CRUD behavior.
   • Example with attributes (modern approach):

     use EasyCorp\Bundle\EasyAdminBundle\Config\Action;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Actions;
     use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
     
     #[Crud]
     #[Actions(list: [Action\DetailAction::new(), Action\EditAction::new()])]
     class User {}
     

2. Field Customization

   • Override default field types (e.g., AssociationField, CollectionField).
   • Add validation or custom logic:

     #[Field(properties: ['form_type' => EmailType::class])]
     public $email;
     

3. List and Filtering

   • Customize the list view with configureListFields():

     public function configureListFields(string $pageName): iterable
     {
         return [
             Field\TextField::new('title')->hideOnDetail(),
             Field\DateTimeField::new('createdAt')->format('Y-m-d'),
         ];
     }
     

   • Add filters via configureFilters():

     public function configureFilters(string $pageName): iterable
     {
         return [
             Filter\TextFilter::new('title'),
             Filter\DateFilter::new('createdAt'),
         ];
     }
     

4. Actions and Buttons

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

     #[Action('publish', icon: 'fas fa-bullhorn', label: 'Publish')]
     public function publishAction(EntityManagerInterface $em, $entity): void
     {
         $entity->setStatus('published');
         $em->flush();
     }
     

5. Security and Permissions

   • Use Symfony’s security system to restrict access:

     # config/packages/easy_admin.yaml
     easy_admin:
         design:
             menu:
                 - { label: 'Dashboard', icon: 'fas fa-home', route: 'app_dashboard', role: 'ROLE_ADMIN' }
     

6. Integration with Forms

   • Extend form types for complex fields:

     use EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext;
     use Symfony\Component\Form\AbstractType;
     
     class CustomFieldType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder->add('custom_field', TextType::class);
         }
     }
     

   • Attach to an entity field:

     #[Field(form_type: CustomFieldType::class)]
     public $customField;
     

Gotchas and Tips

Common Pitfalls

1. Entity Requirements

   • Composite keys or inheritance (e.g., SingleTableInheritance) are unsupported. Use MappedSuperclass or flatten hierarchies.
   • Lazy-loaded associations may cause issues in the admin panel. Fetch eagerly or use ->setFetch('EAGER') in configureFields().

2. Caching Quirks

   • Clear the cache after changes to entity configurations:

     php bin/console cache:clear
     

   • Debugging: Disable caching temporarily in config/packages/easy_admin.yaml:

     easy_admin:
         design:
             assets:
                 css:
                     all: ['bundles/easyadmin/css/easyadmin.all.css']
                 js:
                     all: ['bundles/easyadmin/js/easyadmin.all.js']
     

3. Field Overrides

   • Avoid naming conflicts when overriding fields. Use unique property names or qualify with the entity class:

     Field\AssociationField::new('author')->autocomplete()->setTargetEntityId('App\Entity\User');
     

4. Translation Issues

   • Ensure translations are loaded for the admin panel. Extend the bundle’s translation domain:

     # config/packages/framework.yaml
     framework:
         translator:
             paths:
                 - '%kernel.project_dir%/translations'
             defaults:
                 - '%locale%'
     

5. Performance with Large Datasets

   • Pagination is enabled by default, but optimize queries for complex filters:

     public function configureQuery(string $entityClass): QueryBuilder
     {
         return parent::createQueryBuilder('e')
             ->where('e.status = :status')
             ->setParameter('status', 'active');
     }
     

6. Debugging Tips

   • Enable Symfony’s profiler to inspect queries and rendering:

     # config/packages/dev/debug.yaml
     framework:
         profiler: { only_exceptions: false }
     

   • Check the browser’s console for JavaScript errors (e.g., missing translations or assets).

Extension Points

1. Custom Templates

   • Override Twig templates in templates/EasyAdminBundle/:

     {# templates/EasyAdminBundle/Crud/list.html.twig #}
     {% extends '@EasyAdmin/crud/list.html.twig' %}
     {% block easyadmin_list_row_actions %}
         {{ parent() }}
         <a href="{{ path('app_custom_action', { id: entity.id }) }}">Custom</a>
     {% endblock %}
     

2. Event Listeners

   • Hook into lifecycle events (e.g., prePersist, postRemove):

     use EasyCorp\Bundle\EasyAdminBundle\Event\EasyAdminEvents;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class CustomSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 EasyAdminEvents::PRE_PERSIST => 'onPrePersist',
             ];
         }
     
         public function onPrePersist($event)
         {
             $entity = $event->getEntity();
             $entity->setCreatedAt(new \DateTime());
         }
     }
     

   • Register the subscriber in services.yaml:

     services:
         App\EventListener\CustomSubscriber:
             tags:
                 - { name: kernel.event_subscriber }
     

3. Dynamic Configuration

   • Use AdminContext to conditionally modify behavior:

     use EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext;
     
     public function configureFields(string $pageName, AdminContext $context): iterable
     {
         if ($context->getEntity()->getId() === 1) {
             return [Field\TextField::new('title')->onlyOnDetail()];
         }
         return [Field\TextField::new('title')];
     }
     

4. Asset Management

   • Add custom CSS/JS:

     # config/packages/easy_admin.yaml
     easy_admin:
         design:
             assets:
                 extra_css:
                     - 'bundles/app/css/admin-custom.css'
                 extra_js:
                     - 'bundles/app/js/admin-custom.js'