Pager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require datatheke/pager-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Datatheke\Bundle\PagerBundle\DatathekePagerBundle::class => ['all' => true],
   

2. Basic Usage (Doctrine ORM):

   use Datatheke\Bundle\PagerBundle\Pager\DoctrineORMAdapter;
   use Datatheke\Bundle\PagerBundle\Pager\PagerFactory;
   
   $adapter = new DoctrineORMAdapter($entityManager->getRepository('App\Entity\User')->createQueryBuilder('u'));
   $pager = PagerFactory::createPager($adapter, $request->query->all());
   $pager->setItemsPerPage(10);
   $pager->setCurrentPage($request->query->getInt('page', 1));
   
   return $this->render('template.html.twig', [
       'pager' => $pager,
   ]);
   

3. Twig Integration: Use the pager Twig extension to render the grid:

   {{ pager(pager, 'bootstrap3') }}
   

First Use Case: Doctrine ORM Grid

1. Controller:

   public function listAction(Request $request)
   {
       $qb = $this->getDoctrine()->getRepository('App\Entity\User')->createQueryBuilder('u');
       $adapter = new DoctrineORMAdapter($qb);
       $pager = PagerFactory::createPager($adapter, $request->query->all());
   
       return $this->render('user/list.html.twig', [
           'pager' => $pager,
       ]);
   }
   

2. Twig Template:

   <table class="table table-striped">
       {% for user in pager.items %}
           <tr>
               <td>{{ user.id }}</td>
               <td>{{ user.name }}</td>
           </tr>
       {% endfor %}
   </table>
   {{ pager(pager, 'bootstrap3') }}
   

Implementation Patterns

Adapter Patterns

1. Doctrine ORM:

   $adapter = new DoctrineORMAdapter($qb);
   $adapter->addSort('u.name', 'ASC'); // Sorting
   $adapter->addFilter('u.active', '1'); // Filtering
   

2. Array Data:

   $adapter = new ArrayAdapter($arrayData);
   $adapter->setItemsPerPage(15);
   

3. MongoDB:

   $adapter = new DoctrineMongoDBAdapter($mongoQueryBuilder);
   

Handler Integration (Frontend)

1. DataTables (jQuery):

   {{ pager(pager, 'datatables', {
       'ajax': path('user_list_ajax'),
       'columns': [
           { 'data': 'id' },
           { 'data': 'name' }
       ]
   }) }}
   

2. Bootstrap 3 Theme:

   {{ pager(pager, 'bootstrap3') }}
   

Workflows

1. Pagination + Sorting + Filtering:

   $pager = PagerFactory::createPager($adapter, $request->query->all());
   $pager->setItemsPerPage(20);
   $pager->setCurrentPage($request->query->getInt('page', 1));
   

2. AJAX Handling:

   public function ajaxAction(Request $request)
   {
       $adapter = new DoctrineORMAdapter($qb);
       $pager = PagerFactory::createPager($adapter, $request->query->all());
       return $this->json($pager->getData());
   }
   

3. Console Mode:

   $adapter = new ArrayAdapter($data);
   $pager = PagerFactory::createPager($adapter, [], PagerFactory::MODE_CONSOLE);
   foreach ($pager as $item) {
       print_r($item);
   }
   

Integration Tips

1. Customize Twig Extensions: Override the pager Twig function in your theme by extending the bundle’s templates.

2. Reuse Adapters: Create adapter services in services.yaml for dependency injection:

   services:
       App\Adapter\UserAdapter:
           class: Datatheke\Bundle\PagerBundle\Pager\DoctrineORMAdapter
           arguments: ['@doctrine.orm.entity_manager']
   

3. Event Listeners: Use PagerEvents to modify behavior dynamically (e.g., pre-process filters):

   $dispatcher->addListener(PagerEvents::PRE_FILTER, function ($event) {
       $event->getAdapter()->addFilter('u.status', 'active');
   });
   

Gotchas and Tips

Pitfalls

1. QueryBuilder Modification:

   • The adapter modifies the QueryBuilder directly. Ensure your WHERE/ORDER BY clauses are added after the adapter’s logic if you need custom logic.

2. Pagination Offsets:

   • Doctrine ORM adapters use setFirstResult()/setMaxResults(). For large datasets, ensure your database supports LIMIT/OFFSET efficiently.

3. Twig Template Overrides:

   • If overriding Twig templates, ensure you extend the base template (@DatathekePager/pager.html.twig) to avoid missing variables.

4. Console Mode Quirks:

   • Console mode (MODE_CONSOLE) does not support all frontend handlers. Use array adapters for CLI tools.

Debugging

1. Check Adapter State:

   dump($adapter->getQuery()->getSQL()); // Debug SQL
   dump($adapter->getFilters()); // Inspect filters
   

2. Enable Profiler: Use Symfony’s profiler to inspect the QueryBuilder state after adapter processing.

3. Handler-Specific Issues:

   • For frontend handlers (e.g., DataTables), validate the JSON response matches the expected format:

     {
         "data": [...],
         "recordsTotal": 100,
         "recordsFiltered": 50
     }
     

Configuration Quirks

1. Default Items Per Page: Set globally in config/packages/datatheke_pager.yaml:

   datatheke_pager:
       default_items_per_page: 25
   

2. Theme Overrides: Copy the theme templates from vendor/datatheke/pager-bundle/Resources/views/ to your project’s templates/ directory to customize without losing updates.

3. Handler-Specific Options: Some handlers (e.g., datatables) require additional configuration. Refer to the handler documentation for specifics.

Extension Points

1. Custom Adapters: Extend AbstractAdapter to support new data sources (e.g., Elasticsearch):

   class ElasticsearchAdapter extends AbstractAdapter
   {
       public function __construct($client, $index) { ... }
       public function applyFilters() { ... }
   }
   

2. Custom Handlers: Implement HandlerInterface for new frontend libraries:

   class CustomHandler implements HandlerInterface
   {
       public function render(Pager $pager, array $options) { ... }
   }
   

3. Event Subscribers: Use PagerEvents to inject logic:

   $dispatcher->addListener(PagerEvents::POST_BUILD, function ($event) {
       $event->getPager()->setItemsPerPage(30);
   });
   

Performance Tips

1. Lazy Loading: Use Pager::getIterator() for large datasets to avoid loading all items into memory.

2. Filter Optimization: Apply filters early in the QueryBuilder to reduce the dataset size before pagination:

   $qb->andWhere('u.active = :active')->setParameter('active', 1);
   $adapter = new DoctrineORMAdapter($qb);
   

3. Caching: Cache the QueryBuilder or adapter results if the underlying data rarely changes:

   $adapter->setCache($cachePool);