Datagrid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sonata-project/datagrid-bundle
   

   Add to config/bundles.php:

   SonataProject\DatagridBundle\SonataDatagridBundle::class => ['all' => true],
   

2. First Use Case: Create a basic grid for an App\Entity\User entity:

   # config/packages/sonata_datagrid.yaml
   sonata_datagrid:
       grids:
           user:
               model: App\Entity\User
               actions:
                   _list:
                       subactions:
                           show: ~
                           edit: ~
                           delete: ~
   

3. Controller Integration:

   use Sonata\DatagridBundle\Datagrid\ProxyQueryInterface;
   use Sonata\DatagridBundle\Datagrid\DatagridMapper;
   
   public function listAction(ProxyQueryInterface $datagrid)
   {
       $datagrid->setModelManager($this->getDoctrine()->getManager());
       $datagrid->setPager($this->get('sonata.datagrid.pager'));
       $datagrid->initialize();
   
       return $this->render('user/list.html.twig', [
           'datagrid' => $datagrid,
       ]);
   }
   

4. Twig Template:

   {% for user in datagrid %}
       <tr>
           <td>{{ user.id }}</td>
           <td>{{ user.email }}</td>
           <td>{{ user.createdAt|date('Y-m-d') }}</td>
       </tr>
   {% endfor %}
   

Where to Look First

• Documentation: Sonata Admin Bundle Docs (cross-referenced often).
• Default Config: vendor/sonata-project/datagrid-bundle/Resources/config/services.yaml.
• Example Grids: Check vendor/sonata-project/datagrid-bundle/Tests/App/Resources/config/sonata_datagrid.yaml.

Implementation Patterns

Core Workflow

1. Define Grid in YAML/XML:

   grids:
       advanced_user:
           model: App\Entity\User
           fields:
               id: ~
               email:
                   type: string
                   template: 'user/field_email.html.twig'
               roles:
                   type: twig
                   template: 'user/field_roles.html.twig'
                   options:
                       function: 'getRolesAsString'
           properties:
               createdAt: ~
           group_by: ['roles']
           sort_by: ['createdAt', 'DESC']
   

2. Dynamic Field Mapping:

   $datagrid->addField('custom_field', 'string')
       ->setTemplate('user/custom_field.html.twig')
       ->setOptions(['function' => 'formatCustomField']);
   

3. Pagination & Sorting:

   sonata_datagrid:
       grids:
           paginated_user:
               model: App\Entity\User
               pager:
                   items_per_page: 20
               sort_by: ['id', 'DESC']
   

4. Filtering:

   filters:
       user:
           type: doctrine_orm
           field: email
           options:
               label: 'Email'
               placeholder: 'Filter by email...'
   

Integration Tips

• With Sonata Admin: Extend Sonata\AdminBundle\Datagrid\DatagridMapper for admin-specific grids:

  protected function configureDatagridFilters(DatagridMapper $datagridMapper)
  {
      $datagridMapper->add('id', 'doctrine_orm', ['field' => 'id']);
  }
  

• Custom Query Logic: Override the query via setQuery():

  $datagrid->setQuery($datagrid->getQuery()->where('u.active = 1'));
  

• AJAX Support: Use sonata.datagrid.pager.ajax for infinite scroll:

  {{ sonata_datagrid_pager_ajax(datagrid, 'user_list') }}
  

• Reusable Components: Create base grid classes for shared logic:

  class BaseUserGrid extends AbstractGrid
  {
      public function configure()
      {
          $this->addField('id')->setSortable('id');
          $this->addField('email')->setSortable('email');
      }
  }
  

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • The bundle is archived (last release 2021). Prefer modern alternatives like:
     • KnpPaginatorBundle (for pagination).
     • EasyAdminBundle (for admin grids).
     • API Platform (for data grids in APIs).

2. Doctrine Proxy Issues:

   • If using proxies, ensure ProxyQueryInterface is injected correctly:

     $datagrid->setModelManager($this->getDoctrine()->getManagerForClass(User::class));
     

3. Caching Quirks:

   • Grid configurations are cached. Clear cache after changes:

     php bin/console cache:clear
     

4. Field Type Conflicts:

   • Avoid naming conflicts with Symfony’s field types (e.g., text vs. sonata_type_text).

Debugging

1. Query Dumping: Enable Doctrine debugging to inspect generated queries:

   # config/packages/dev/doctrine.yaml
   doctrine:
       dbal:
           logging: true
           profiling: true
   

2. Grid Dumping: Log the grid configuration for debugging:

   \Symfony\Component\Debug\Debug::dump($datagrid->getConfiguration());
   

3. Common Errors:

   • "No model manager found": Ensure setModelManager() is called.
   • "Field not found": Verify field names match entity properties (case-sensitive).
   • "Pager not configured": Add pager: ~ to grid config.

Tips

1. Performance:

   • Use DISTINCT for grouped queries:

     group_by: ['department']
     distinct: true
     

   • Limit fields in queries to avoid SELECT *:

     fields:
         id: ~
         name: ~
     

2. Extending:

   • Create custom field types by extending Sonata\DatagridBundle\Type\Field\FieldTypeInterface.
   • Example:

     class CustomFieldType extends AbstractType
     {
         public function buildView(FormView $view, FormInterface $form, array $options)
         {
             $view->vars['custom_option'] = $options['custom_option'];
         }
     }
     

3. Testing:

   • Mock ProxyQueryInterface in PHPUnit:

     $datagrid = $this->createMock(ProxyQueryInterface::class);
     $datagrid->method('getQuery')->willReturn($queryBuilder);
     

4. Legacy Migration:

   • If migrating from Sonata Admin, copy grid configs from sonata_admin to sonata_datagrid:

     # Before (Sonata Admin)
     sonata_admin:
         grids:
             user:
                 fields: [...]
     
     # After (Sonata Datagrid)
     sonata_datagrid:
         grids:
             user:
                 model: App\Entity\User
                 fields: [...]