Doctrine Orm Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require admin-project/doctrine-orm-admin-bundle
   

   Add to config/bundles.php (Symfony):

   AdminProject\DoctrineOrmAdminBundle\AdminProjectDoctrineOrmAdminBundle::class => ['all' => true],
   

2. Basic Configuration Register the bundle in config/packages/admin_project_doctrine_orm_admin.yaml:

   admin_project_doctrine_orm_admin:
       orm:
           enabled: true
           entities:
               - App\Entity\YourEntity
   

3. First Use Case Create a CRUD admin interface for an entity:

   // src/Admin/YourEntityAdmin.php
   namespace App\Admin;
   
   use AdminProject\DoctrineOrmAdminBundle\Admin\AbstractAdmin;
   use App\Entity\YourEntity;
   
   class YourEntityAdmin extends AbstractAdmin
   {
       protected static $entity = YourEntity::class;
   }
   

4. Auto-Discovery The bundle auto-discovers Admin/ classes in src/. No manual registration needed.

Implementation Patterns

Common Workflows

1. Customizing Fields Override configureFields() to modify displayed fields:

   protected function configureFields(string $pageName): iterable
   {
       return [
           'id' => 'Id',
           'name' => 'Name',
           'createdAt' => 'Created At',
       ];
   }
   

2. Filtering Add filters in configureFilters():

   protected function configureFilters(string $pageName): iterable
   {
       return [
           'name' => 'Name',
           'active' => 'Active (Boolean)',
       ];
   }
   

3. Actions Add custom actions (e.g., bulk delete):

   protected function configureActions(): iterable
   {
       return [
           'delete' => [
               'label' => 'Delete',
               'icon' => 'delete',
               'type' => 'delete',
           ],
       ];
   }
   

4. Form Customization Override configureFormFields() for edit/create forms:

   protected function configureFormFields(string $pageName): iterable
   {
       return [
           'name' => 'Name',
           'description' => 'Description (Textarea)',
       ];
   }
   

5. Entity Relationships Handle relationships (e.g., ManyToOne):

   protected function configureFields(string $pageName): iterable
   {
       return [
           'user.name' => 'User',
           'posts.count' => 'Post Count',
       ];
   }
   

Integration Tips

1. Symfony Forms Integration Use Symfony’s FormBuilder for complex fields:

   public function configureFormFields(string $pageName): iterable
   {
       return [
           'tags' => 'Tags (Collection)',
           'settings' => 'Settings (Form)',
       ];
   }
   

2. Doctrine Lifecycle Callbacks Leverage Doctrine events (e.g., @PrePersist) via the entity, not the admin class.

3. Translation Use Symfony’s translation system for labels:

   # config/packages/admin_project_doctrine_orm_admin.yaml
   admin_project_doctrine_orm_admin:
       translation_domain: 'admin'
   

4. Security Restrict access via Symfony’s voters or ACLs:

   public function configurePermissions(): array
   {
       return ['ROLE_ADMIN'];
   }
   

5. API Integration Extend with API endpoints by combining with Symfony’s Serializer or ApiPlatform.

Gotchas and Tips

Pitfalls

1. Entity Not Found

   • Issue: Class "App\Entity\YourEntity" is not mapped.
   • Fix: Ensure the entity is annotated/configured in Doctrine (@ORM\Entity).
   • Debug: Run php bin/console doctrine:schema:validate.

2. Field Not Displaying

   • Issue: Custom fields (e.g., user.name) fail silently.
   • Fix: Verify the relationship exists in the entity and use the correct property path.

3. Caching Issues

   • Issue: Changes to admin classes aren’t reflected.
   • Fix: Clear cache:

     php bin/console cache:clear
     

4. Overriding Defaults

   • Issue: configureFields() doesn’t override defaults.
   • Fix: Use parent::configureFields() and merge:

     $fields = parent::configureFields($pageName);
     $fields['custom'] = 'Custom Field';
     return $fields;
     

5. Performance with Large Datasets

   • Issue: Slow loading due to N+1 queries.
   • Fix: Use DQL or QueryBuilder in configureDatagrid():

     protected function configureDatagridFilters(string $pageName): iterable
     {
         return [
             'query' => function (DatagridMapper $datagridMapper) {
                 $datagridMapper->add('e.name', 'Name');
                 $datagridMapper->add('COUNT(p.id)', 'Post Count');
             },
         ];
     }
     

Debugging Tips

1. Enable Debug Mode Set APP_DEBUG=true in .env to see detailed errors.

2. Log Queries Enable Doctrine logging in config/packages/doctrine.yaml:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

3. Check Admin Routes List all admin routes:

   php bin/console debug:router | grep admin
   

4. Inspect Generated HTML Use browser dev tools to verify rendered fields/actions.

Extension Points

1. Custom Templates Override Twig templates in templates/admin/:

   {# templates/admin/YourEntity/index_content.html.twig #}
   {% extends '@AdminProjectDoctrineOrmAdmin/admin/crud/index_content.html.twig' %}
   

2. Event Listeners Subscribe to admin events:

   // src/EventListener/AdminListener.php
   namespace App\EventListener;
   
   use AdminProject\DoctrineOrmAdminBundle\Event\AdminEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class AdminListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               AdminEvent::PRE_SAVE => 'onPreSave',
           ];
       }
   
       public function onPreSave(AdminEvent $event): void
       {
           $entity = $event->getEntity();
           // Modify entity before save
       }
   }
   

3. Custom Field Types Create a custom field type:

   namespace App\Admin\Field;
   
   use AdminProject\DoctrineOrmAdminBundle\Field\AbstractField;
   
   class CustomField extends AbstractField
   {
       public function getBlockPrefix(): string
       {
           return 'custom_field';
       }
   
       public function configureOptions(OptionsResolver $resolver): void
       {
           $resolver->setDefaults([
               'label' => 'Custom Field',
           ]);
       }
   }
   

   Register in services.yaml:

   services:
       App\Admin\Field\CustomField:
           tags: [admin_project.doctrine_orm_admin.field]
   

4. Bulk Actions Extend bulk actions via configureActions():

   protected function configureActions(): iterable
   {
       return [
           'export' => [
               'label' => 'Export',
               'type' => 'export',
               'handler' => [$this, 'exportHandler'],
           ],
       ];
   }
   
   public function exportHandler(): void
   {
       // Custom export logic
   }
   

5. Internationalization Use Symfony’s translation system for dynamic labels:

   protected function configureFields(string $pageName): iterable
   {
       return [
           'name' => $this->translator->trans('admin.your_entity.name'),
       ];
   }