Pageon Doctrine Data Grid Bundle Laravel Package

Getting Started

Because this bundle has a single star and no dependents, treat the source as the documentation — read src/ before writing any code.

1. Install the bundle and its hard dependency, KnpPaginatorBundle:

   composer require pageon/pageon-doctrine-data-grid-bundle
   composer require knplabs/knp-paginator-bundle
   

2. Register both bundles in config/bundles.php:

   return [
       Knp\Bundle\PaginatorBundle\KnpPaginatorBundle::class => ['all' => true],
       Pageon\DoctrineDataGridBundle\PageonDoctrineDataGridBundle::class => ['all' => true],
   ];
   

3. Check the bundle's own service/config under vendor/pageon/pageon-doctrine-data-grid-bundle/. The bundle ships no user-facing config tree in most cases — most wiring happens in your controllers through the grid classes the bundle exposes. Confirm the exact constructor signatures here; they matter more than any online doc.

4. First use case — the intended one: an admin listing screen for a Doctrine entity. Build a grid service/class around a QueryBuilder, point it at your entity, define a handful of columns, and render it through the bundle's Twig template with knp_pagination_render(...) for the pager.

The realistic "hello world" is: take one existing controller that dumps a plain findAll() table, wrap its QueryBuilder in the bundle's grid object, and let KnpPaginator take over pagination. That is the smallest meaningful integration and the quickest way to see what the package actually buys you.

Implementation Patterns

Grid-as-a-service, one per entity. The cleanest pattern is to define one grid class per entity listing and inject it into the controller. This keeps the QueryBuilder, column definitions, and sort whitelist in one testable place rather than scattering them across actions.

Build the grid from a QueryBuilder, not from a repository. Since KnpPaginator paginates any query, feed the grid a QueryBuilder (or the paginator's PaginatorInterface + your Query object). This lets you pre-apply tenant filters, soft-delete filters, or joins before the grid ever sees the data:

$qb = $this->productRepository->createQueryBuilder('p')
    ->leftJoin('p.category', 'c')
    ->addSelect('c');

$grid = $this->productGrid->forQuery($qb);

Column definitions drive both rendering and sorting. Whitelist sortable columns explicitly — never derive the sort field from the request. Most KnpPaginator-based grids break here if you skip the whitelist, because KnpPaginator will happily accept ?sort=anything and try to addOrderBy it.

Keep Twig thin. Render the whole grid through the bundle's template and let it iterate columns. For any custom cell (badges, action links, formatted currency), the practical extension point is an overridable column template or a per-column render callback rather than editing the vendor template in place.

Compose with filters via KnpPaginator's filter listeners. If the grid needs date-range or search filtering, use Knp's Sortable/search adapter rather than re-implementing filtering — the bundle is a thin wrapper and will not manage filter state for you.

Reuse a base grid class. If you have six admin listings, a small abstract grid (entity class, default sort, page size, common columns like createdAt and id) pays off immediately. The package gives you almost no opinion here, so this is where your architecture lives.

Gotchas and Tips

• Verify Symfony compatibility first. With one star and no dependents, this bundle almost certainly lags current Symfony releases. Check composer.json's symfony/* and knplabs/knp-paginator-bundle constraints before committing — a hard ^4.4 constraint on a Symfony 6/7 app is a common dead end. Fork or override the version constraint locally if needed.

• Join hydration + pagination. When you paginate over a joined query with addSelect, KnpPaginator's count query can misbehave if the join produces duplicates. Use DISTINCT on the root entity or switch to ->select('p') for the count. This is a KnpPaginator trait, not a bundle bug, but it will bite you here.

• Sort whitelisting is non-negotiable. If the bundle exposes any request-to-sort mapping, confirm in the source whether it whitelists. Assume it does not and add your own whitelist. This is the single highest-risk area because it borders on SQL injection.

• No config tree = read the source. There is no documentation site worth visiting. The bundle's public surface is whatever its classes expose; check for constructor-injected EntityManagerInterface vs. ManagerRegistry and whether templates are namespaced (@PageonDoctrineDataGrid/...) or referenced by path.

• Template overrides go in templates/bundles/PageonDoctrineDataGridBundle/, following standard Symfony bundle convention, if you need to change markup (e.g., Bootstrap 5 vs. table markup). Prefer overriding over editing vendor/.

• Debug pagination failures by checking the paginator directly. When a grid renders empty, the bundle is rarely the cause — dump the PaginatorInterface result in isolation ($paginator->paginate($query, $page, $limit)) to confirm whether the problem is query construction, count query, or template rendering.

• Treat this as a thin wrapper you can replace. Given its maturity, the pragmatic risk mitigation is to keep your grid-building logic in your own classes and let the bundle supply only the pagination glue and template. If it breaks on upgrade, swapping it out becomes a composer remove rather than a rewrite.