Pagerfanta Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require white-october/pagerfanta-bundle
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle::class => ['all' => true],
   ];
   

2. First Use Case: Basic Pagination in a Controller

   use WhiteOctober\PagerfantaBundle\Pagerfanta\PagerfantaAdapter;
   use Pagerfanta\Pagerfanta;
   
   public function indexAction()
   {
       $data = $this->getDoctrine()->getRepository('App:Post')->findAll();
       $adapter = new PagerfantaAdapter(new ArrayAdapter($data));
       $pagerfanta = new Pagerfanta($adapter);
       $pagerfanta->setMaxPerPage(10);
   
       return $this->render('post/index.html.twig', [
           'pagerfanta' => $pagerfanta,
       ]);
   }
   

3. Render in Twig

   {{ pagerfanta|pagerfanta_default('post/index') }}
   

Implementation Patterns

Common Workflows

1. Doctrine ORM Integration Use DoctrineORMAdapter for seamless pagination with Doctrine repositories:

   $query = $this->getDoctrine()->getRepository('App:Post')->createQueryBuilder('p')->getQuery();
   $adapter = new DoctrineORMAdapter($query);
   $pagerfanta = new Pagerfanta($adapter);
   

2. Custom Views Extend default views by creating a new Twig template (e.g., views/pagerfanta/custom.html.twig) and pass it to the Twig filter:

   {{ pagerfanta|pagerfanta_custom('post/index') }}
   

3. Reusing Options Define reusable options in config/packages/white_october_pagerfanta.yaml:

   white_october_pagerfanta:
       views:
           default:
               options:
                   previous: '« Previous'
                   next: 'Next »'
   

4. Dynamic Max Per Page Allow users to select items per page:

   $pagerfanta->setMaxPerPage($request->query->getInt('per_page', 10));
   

5. AJAX Pagination Use pagerfanta_ajax Twig filter for AJAX-driven pagination:

   {{ pagerfanta|pagerfanta_ajax('post/index', { 'per_page': 20 }) }}
   

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch

   • The bundle is outdated (last release: 2018). For Symfony 4/5, use white-october/pagerfanta-bundle only if you’re on Symfony 2.0+ (check composer.json constraints).
   • Workaround: Fork the repo and update dependencies manually or switch to knplabs/knp-paginator-bundle (modern alternative).

2. Twig Filter Overrides

   • If pagerfanta_default or pagerfanta_custom filters don’t work, ensure:
     • The bundle is registered in bundles.php.
     • Twig extensions are loaded (check config/packages/twig.yaml for conflicts).

3. Doctrine Query Caching

   • Pagerfanta’s DoctrineORMAdapter may cache queries aggressively. Disable caching if needed:

     $query->setMaxResults(10)->setFirstResult(($page-1)*10); // Manual pagination
     

4. CSRF in AJAX Requests

   • AJAX pagination may fail due to CSRF protection. Exclude the route in config/packages/security.yaml:

     access_control:
         - { path: ^/ajax/pagerfanta, roles: PUBLIC_ACCESS }
     

Debugging Tips

1. Check Pagerfanta Instance Dump the Pagerfanta object to verify data:

   dump($pagerfanta->getCurrentPageResults()->count());
   

2. Inspect Twig Variables Use {{ dump(pagerfanta) }} in Twig to debug the passed object structure.

3. Clear Cache After modifying white_october_pagerfanta.yaml, run:

   php bin/console cache:clear
   

Extension Points

1. Custom Adapter Extend PagerfantaAdapter for non-Doctrine data sources (e.g., Elasticsearch):

   class ElasticsearchAdapter extends Pagerfanta\Adapter\AdapterInterface {
       public function getItems($offset, $length) { /* ... */ }
       public function getNbItems() { /* ... */ }
   }
   

2. Override Twig Filters Create a custom Twig extension to modify pagination behavior:

   // src/Twig/PagerfantaExtension.php
   class PagerfantaExtension extends \Twig\Extension\AbstractExtension {
       public function getFunctions() {
           return [
               new \Twig\TwigFunction('custom_pagerfanta', [$this, 'renderPagerfanta']),
           ];
       }
   }
   

3. Dynamic View Selection Pass dynamic view names based on user roles or contexts:

   {% set view = app.user ? 'admin_pager' : 'default' %}
   {{ pagerfanta|pagerfanta(view) }}