Paginator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anh/paginator-bundle
   

   Enable the bundle in config/bundles.php:

   Anh\PaginatorBundle\AnhPaginatorBundle::class => ['all' => true],
   

2. Basic Usage Register the paginator service in config/services.yaml:

   anh_paginator:
       class: Anh\Paginator\Paginator
       arguments: ['@doctrine.orm.entity_manager']
   

3. First Use Case Paginate Doctrine results in a controller:

   use Anh\PaginatorBundle\Paginator\Paginator;
   
   class ProductController extends AbstractController
   {
       public function list(Paginator $paginator, int $page = 1)
       {
           $query = $this->getDoctrine()
               ->getRepository(Product::class)
               ->createQueryBuilder('p')
               ->getQuery();
   
           $results = $paginator->paginate($query, $page, 10); // 10 items/page
           return $this->render('product/list.html.twig', [
               'results' => $results,
           ]);
       }
   }
   

4. Twig Integration Use the paginator Twig extension for rendering:

   {% for product in results %}
       {{ product.name }}
   {% endfor %}
   
   {{ paginator(results) }}
   

Implementation Patterns

Common Workflows

1. Doctrine Pagination

   $query = $entityManager->createQuery('SELECT u FROM App\Entity\User u');
   $paginated = $paginator->paginate($query, $page, 20);
   

2. Custom QueryBuilder

   $qb = $entityManager->getRepository(Product::class)
       ->createQueryBuilder('p')
       ->where('p.price > :min')
       ->setParameter('min', 10);
   
   $results = $paginator->paginate($qb, $page, 15);
   

3. Dynamic Page Handling

   $page = $request->query->getInt('page', 1);
   $results = $paginator->paginate($query, $page, 10);
   

4. API Responses

   $data = [
       'data' => $results->getResults(),
       'meta' => [
           'page' => $results->getPage(),
           'total_pages' => $results->getTotalPages(),
       ],
   ];
   return $this->json($data);
   

Integration Tips

• Symfony Forms: Use Anh\PaginatorBundle\Form\Type\PaginatorType for form-based pagination.
• Event Listeners: Extend Anh\PaginatorBundle\Event\PaginatorEvent for pre/post-pagination logic.
• Caching: Cache paginated results with Anh\Paginator\Cache\CacheInterface if using Doctrine caching.
• Custom Templates: Override Twig templates in templates/AnhPaginatorBundle/ for theming.

Gotchas and Tips

Pitfalls

1. Doctrine Version Mismatch

   • The bundle requires Symfony 2.5+ and Doctrine ORM. If using Symfony 3/4/5, ensure compatibility by checking anh/paginator version constraints.
   • Fix: Use anh/paginator:^0.2 and verify Doctrine integration in tests.

2. Query Cloning Issues

   • The paginator clones queries internally. Complex QueryBuilder setups (e.g., custom DQL or HydrationMode) may break.
   • Fix: Simplify queries or use ->getQuery() directly instead of QueryBuilder.

3. Pagination Links in Twig

   • Default Twig templates assume URL generation via path() or url(). For API routes, override templates or use paginator(results, {'route': 'api_product_list'}).

4. Performance with Large Datasets

   • The bundle uses SET FIRST RESULT/SET MAX RESULTS, which can be slow for unoptimized queries.
   • Fix: Add indexes to filtered/sorted fields (e.g., WHERE, ORDER BY).

Debugging

• Check Paginated Results

  var_dump($results->getResults()); // Array of entities
  var_dump($results->getTotalItems()); // Total count
  

• Log Queries Enable Doctrine logging to inspect generated SQL:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
          profiling: true
  

Configuration Quirks

1. Default Items per Page Override in config/packages/anh_paginator.yaml:

   anh_paginator:
       items_per_page: 15 # Default for all paginators
   

2. Custom Paginator Class Extend Anh\Paginator\Paginator and bind it as a service:

   services:
       App\Service\CustomPaginator:
           class: App\Service\CustomPaginator
           arguments: ['@doctrine.orm.entity_manager']
           tags: ['anh_paginator.paginator']
   

Extension Points

1. Custom Paginator Adapter Implement Anh\Paginator\Adapter\AdapterInterface for non-Doctrine data sources (e.g., Elasticsearch):

   class ElasticAdapter implements AdapterInterface
   {
       public function getResults(QueryInterface $query, $offset, $limit)
       {
           // Custom logic
       }
       public function getTotalItems(QueryInterface $query)
       {
           // Custom logic
       }
   }
   

2. Event Subscribers Listen to paginator.pre_paginate or paginator.post_paginate events:

   use Anh\PaginatorBundle\Event\PaginatorEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MySubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               PaginatorEvent::PRE_PAGINATE => 'onPrePaginate',
               PaginatorEvent::POST_PAGINATE => 'onPostPaginate',
           ];
       }
   
       public function onPrePaginate(PaginatorEvent $event)
       {
           $event->setItemsPerPage(30); // Modify dynamically
       }
   }
   

3. Twig Filters Extend Twig with custom filters for paginated data:

   {{ results|custom_filter }}
   

   // src/Twig/AppExtension.php
   public function getFilters()
   {
       return [
           new \Twig\TwigFilter('custom_filter', [$this, 'customFilter']),
       ];
   }