Datagrid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coryjb/datagrid-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       CoryJB\DatagridBundle\CoryJBDatagridBundle::class => ['all' => true],
   ];
   

2. Basic Usage Create a controller to render a grid:

   use CoryJB\DatagridBundle\Datagrid\Datagrid;
   use CoryJB\DatagridBundle\Datagrid\Source\DoctrineSource;
   
   class ProductController extends AbstractController
   {
       public function listAction()
       {
           $grid = new Datagrid();
           $grid->setSource(new DoctrineSource(Product::class));
   
           $grid->addColumn('id', 'ID', 'text');
           $grid->addColumn('name', 'Name', 'text');
   
           return $this->render('@CoryJBDatagrid/Grid.html.twig', [
               'grid' => $grid,
           ]);
       }
   }
   

3. First Use Case Display a paginated list of entities with sorting/filtering:

   {{ render(controller('App\Controller\ProductController::listAction')) }}
   

Implementation Patterns

Common Workflows

1. Dynamic Column Configuration Use addColumn() with custom callbacks for computed fields:

   $grid->addColumn('price', 'Price', 'text', function ($entity) {
       return '$' . number_format($entity->getPrice(), 2);
   });
   

2. Doctrine Integration Leverage DoctrineSource for automatic DQL generation:

   $source = new DoctrineSource(Product::class, $entityManager);
   $source->addFilter('active', true); // WHERE active = 1
   $grid->setSource($source);
   

3. Twig Integration Extend templates via Grid.html.twig overrides:

   {% extends '@CoryJBDatagrid/Grid.html.twig' %}
   {% block grid_row %}
       <tr>
           <td>{{ entity.id }}</td>
           <td><a href="{{ path('product_edit', {'id': entity.id}) }}">{{ entity.name }}</a></td>
       </tr>
   {% endblock %}
   

4. API Responses Return JSON for SPAs:

   $grid->setResponseFormat('json');
   return $this->json($grid->getData());
   

Integration Tips

• Event Listeners: Attach to datagrid.build events for pre-processing.
• Custom Sources: Implement SourceInterface for non-Doctrine data (e.g., CSV, API).
• Caching: Cache grid configurations or query results for performance.

Gotchas and Tips

Pitfalls

1. Doctrine DQL Quirks

   • Complex joins may require manual DQL in DoctrineSource.
   • Avoid IN clauses with large datasets (use FIND_IN_SET or native queries).

2. Pagination Edge Cases

   • Ensure setItemsPerPage() is called before getData().
   • Test with empty datasets to avoid division-by-zero in pagination controls.

3. Twig Template Overrides

   • Block names (grid_header, grid_row) must match exactly.
   • Clear cache after template changes (php bin/console cache:clear).

Debugging

• Enable SQL Logging

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

• Check Grid Events

  $grid->on('build', function ($event) {
      \CoryJB\DatagridBundle\Event\BuildEvent $event;
      dump($event->getGrid()->getSource()->getQuery());
  });
  

Extension Points

1. Custom Column Types Extend Column\AbstractColumn for new renderers (e.g., DateColumn):

   class DateColumn extends AbstractColumn
   {
       public function render($entity)
       {
           return $entity->getCreatedAt()->format('Y-m-d');
       }
   }
   

2. Filter Extensions Add custom filters via addFilter() with FilterInterface:

   $grid->addFilter('search', new SearchFilter('name', 'LIKE', '%{value}%'));
   

3. Action Buttons Use addAction() for row-level actions:

   $grid->addAction('edit', 'Edit', function ($entity) {
       return $this->generateUrl('product_edit', ['id' => $entity->getId()]);
   });