Paginator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require pagerfanta/pagerfanta da/paginator-bundle
   

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

   return [
       // ...
       Da\PaginatorBundle\DaPaginatorBundle::class,
   ];
   

2. First Use Case: Fetch paginated data from an array in a controller:

   use Symfony\Component\HttpFoundation\Request;
   
   public function indexAction(Request $request)
   {
       $paginator = $this->get('da_paginator.paginator');
       $data = [/* your array data */];
   
       $paginatedContent = $paginator->defineOffsetPaginatedContent(
           ['id', 'name'], // fields to display
           'array',
           $data,
           $request->query->getInt('page', 1), // current page
           5 // items per page
       );
   
       return $this->render('template.html.twig', [
           'paginatedContent' => $paginatedContent,
       ]);
   }
   

3. Twig Integration: Use the pagerfanta Twig extension to render pagination links:

   {{ paginator(paginatedContent) }}
   

Implementation Patterns

Common Workflows

1. Database Pagination: Use defineDoctrinePaginatedContent for Doctrine ORM queries:

   $paginatedContent = $paginator->defineDoctrinePaginatedContent(
       $entityRepository->createQueryBuilder('e'),
       $request->query->getInt('page', 1),
       10
   );
   

2. Dynamic Field Mapping: Map fields dynamically (e.g., for API responses):

   $fields = ['id', 'name', 'createdAt'];
   $paginatedContent = $paginator->defineOffsetPaginatedContent(
       $fields,
       'array',
       $data,
       $page,
       $limit
   );
   

3. Custom Adapter: Extend Pagerfanta\Adapter\AdapterInterface for non-standard data sources (e.g., Elasticsearch):

   $adapter = new CustomAdapter($client->search());
   $paginator = new Pagerfanta(new CustomAdapter($adapter));
   

4. API Pagination: Return paginated JSON responses:

   return $this->json([
       'data' => $paginatedContent->getCurrentPageResults(),
       'pagination' => [
           'total' => $paginatedContent->getNbResults(),
           'pages' => $paginatedContent->getNbPages(),
           'current' => $paginatedContent->getCurrentPage(),
       ],
   ]);
   

Integration Tips

• Symfony Forms: Use Pagerfanta\Bridge\Doctrine\ORM\QueryAdapter with Symfony\Bridge\Doctrine\Form\Type\EntityType for paginated form fields.
• API Platform: Combine with ApiPlatform\Core\Bridge\Doctrine\Orm\Paginator for standardized API pagination.
• Event Listeners: Attach listeners to Pagerfanta\Event\InitializeEvent for pre-pagination logic (e.g., filtering).

Gotchas and Tips

Pitfalls

1. Field Mapping Errors:

   • Ensure field names in defineOffsetPaginatedContent match the array keys exactly (case-sensitive).
   • Debug with var_dump($data[0]) to verify structure.

2. Doctrine Pagination Quirks:

   • Use setFirstResult() and setMaxResults() explicitly if defineDoctrinePaginatedContent behaves unexpectedly.
   • Avoid DISTINCT in queries—it can break pagination counts.

3. Performance:

   • Large datasets may cause memory issues. Use Pagerfanta\Pagerfanta with Pagerfanta\Adapter\LimitedAdapter to limit loaded items:

     $adapter = new LimitedAdapter($originalAdapter, 100);
     

4. Twig Debugging:

   • If {{ paginator(paginatedContent) }} renders nothing, check:
     • The pagerfanta Twig extension is enabled (da_paginator.twig.pagerfanta service).
     • The paginatedContent object is valid (call isValid()).

Debugging Tips

• Log Pagination Data:

  $this->get('logger')->debug(
      'Pagination Data',
      [
          'total' => $paginatedContent->getNbResults(),
          'page' => $paginatedContent->getCurrentPage(),
          'items' => count($paginatedContent->getCurrentPageResults()),
      ]
  );
  

• Check Adapter: Verify the adapter returns correct data:

  $adapter = $paginatedContent->getAdapter();
  $data = $adapter->getSlice(0, 10); // Test first 10 items
  

Extension Points

1. Custom Twig Functions: Extend the Twig environment to add custom pagination templates:

   $twig->addFunction(new \Twig\TwigFunction('custom_paginator', [$this, 'renderCustomPaginator']));
   

2. Override Paginator Service: Replace the default service in services.yaml:

   da_paginator.paginator:
       class: App\Service\CustomPaginator
       arguments: ['@pagerfanta.factory']
   

3. Add Metadata: Extend Da\PaginatorBundle\Paginator\Paginator to include custom metadata (e.g., API links):

   public function getApiLinks() { /* ... */ }
   

4. Event Subscribers: Listen for Pagerfanta\Event\ViewEvent to modify rendered pagination:

   $view->variables['custom_var'] = 'value';