Data Dog Pager Bundle Laravel Package

Getting Started

Before installing, confirm your project is actually a Symfony 2.x / PHP 5.x–7.x application. This bundle targets Symfony2 and Doctrine ORM and was not written for Symfony 3+, Flex, or modern PHP; if you're on Symfony 4/5/6 the composer constraint will almost certainly fail or drag in incompatible dependencies. The realistic "day one" audience is a legacy Symfony2 app that needs pagination on an admin or listing screen.

Minimal steps:

1. composer require granedirval/data-dog-pager-bundle
2. Register the bundle in app/AppKernel.php:

   new GraneDirval\DataDogPagerBundle\DataDogPagerBundle(),
   

3. Open the README first — that's where service IDs, config keys, and filter/sorter registration are documented. There is no maintained docs site, so the repo is the source of truth.
4. Locate the pager service in Resources/config/services.xml (the bundle's DI file) to see the exact service alias before wiring anything.

First use case — paginating a Doctrine query builder in a controller:

$qb = $em->getRepository('AppBundle:Product')->createQueryBuilder('p')
    ->where('p.active = :active')
    ->setParameter('active', true);

$pager = $this->get('data_dog_pager')->paginate($qb, $page, 20);
// or whatever the actual service id is per the repo README

Then hand $pager (or its items + pager metadata) to Twig. The bundle's core job is small: wrap a QueryBuilder, apply filters/sorters, run a count query, apply offset/limit, and expose page metadata. Get that loop working on one controller before touching filters or sorters.

Implementation Patterns

Controller-driven pagination. Keep the pager invocation in the controller or a small application service — don't bury it in entities or repositories. Fetch the page from $request->query->getInt('page', 1), clamp the limit, and build the query builder immediately above the paginate() call so the query is easy to read and debug.

Filters. The bundle's differentiating feature is filters layered on top of a base query builder. The pattern that works best:

• Read filter parameters from $request->query (not the session), so pagination URLs are shareable and back/forward works.
• Apply only whitelisted filters — never pass user input straight into column names.
• Build the base QB, apply filters, then hand it to the pager. If filters change the row count (joins, HAVING, GROUP BY), verify the count query the bundle generates matches the data query.

Sorters. Same rule: whitelist sortable columns and ASC/DESC, then apply the orderBy before pagination. A common pattern is a $sortable = ['createdAt', 'name', 'price'] array mapped to actual columns. Sort state must travel in the query string alongside the page number, otherwise clicking "page 2" silently drops the sort.

Twig rendering. Iterate the paged items for the table/list, then render pagination controls from the pager's metadata (current page, total pages, has-next/prev). If the bundle ships a template, extend or copy it rather than rebuilding — it will encode the expected metadata keys. If it doesn't, you'll render links like ?page={{ page }}&{{ app.request.query.all|url_encode }} and strip the page key, or build the URL with the existing query params merged.

Reusable list action. If you have several paginated screens, write one base controller method or trait that accepts a QueryBuilder, a filter map, and a sorter map, and returns the pager + filters + sort state. That keeps filter/sorter behavior consistent and makes the odd broken list easy to spot.

Integration tips.

• Put filter/sorter whitelists next to the controller, not in the bundle config, unless the bundle explicitly supports registering them there.
• Keep the page size in a constant or controller parameter; don't let it drift per action.
• If you use Sonata Admin, check whether this bundle coexists cleanly; Sonata has its own pagers and dual pagination is a classic footgun.

Gotchas and Tips

• Abandonment risk is the headline. Zero dependents and a blank star count mean essentially no community validation. Treat adoption as "inherit and maintain." Read the source of the pager class before committing — it's small enough to audit in an afternoon, and you'll need to understand it when Symfony/Doctrine upgrade breaks it.
• Symfony2 is EOL. No security patches for the framework, and this bundle compounds the risk. Any migration to Symfony 3+ will likely require forking and repointing the bundle's service definitions.
• Count-query drift. With GROUP BY, DISTINCT, or joins that fan out rows, a pager's count query over-counts and you get phantom pages or truncated results. Inspect the count query via the Doctrine logger; if it's wrong, the usual fix is to hand the pager a separate count QueryBuilder or de-duplicate with DISTINCT.
• N+1 fetches. Pagination limits the root entity but not lazy-loaded relations in the Twig loop. Add leftJoin/addSelect (fetch joins) for relations you render, or you'll fire a query per row.
• Sort/filter parameter persistence. The most common bug is sort state vanishing on page change because only page is propagated. Explicitly merge all active filter/sort query parameters into every generated pager URL.
• SQL injection on sort/filter names. Do not concatenate user strings into orderBy or field names. Map through a whitelist.
• Extension points. The bundle's intended extensibility is custom filter and sorter classes. If you need behavior it lacks (e.g., a date-range filter with custom SQL), subclass or implement against whatever interface the bundle exposes rather than hacking the base pager.
• Debugging. Log the generated SQL ($qb->getQuery()->getSQL()) right before paginate() and inspect the count query separately. If pages come back empty, check that offset/limit are applied after filters and sorts, and that the limit isn't being overwritten by a config default.
• Prefer an alternative if greenfield. For any new Symfony project, use Pagerfanta with its Doctrine adapters — maintained, documented, and has real community support. This bundle only makes sense when you're maintaining an existing Symfony2 app and want a drop-in pager with filter/sorter conventions already in place.