Pagination Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coka/pagination-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       CedrickOka\PaginationBundle\OkaPaginationBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Controller:

     use CedrickOka\PaginationBundle\Pagination\PaginatorInterface;
     use Symfony\Component\HttpFoundation\Request;
     
     public function index(PaginatorInterface $paginator, Request $request)
     {
         $queryBuilder = $this->getDoctrine()->getRepository(MyEntity::class)->createQueryBuilder('e');
         $pagination = $paginator->paginate(
             $queryBuilder,
             $request->query->getInt('page', 1),
             10 // items per page
         );
         return $this->render('my_template.html.twig', ['pagination' => $pagination]);
     }
     

   • Twig Template:

     {% for item in pagination.items %}
         {{ item.name }}
     {% endfor %}
     
     {{ pagination|oka_pagination }}
     

3. Key Files:

   • docs/index.md for core concepts.
   • src/Resources/views/ for default Twig templates (overrideable).

Implementation Patterns

Common Workflows

1. QueryBuilder Pagination:

   $queryBuilder = $entityManager->getRepository(MyEntity::class)
       ->createQueryBuilder('e')
       ->where('e.status = :status')
       ->setParameter('status', 'active');
   
   $pagination = $paginator->paginate($queryBuilder, $page, $limit);
   

2. Array Pagination (for non-DB data):

   $items = $this->getArrayData(); // e.g., API responses
   $pagination = $paginator->paginateArray($items, $page, $limit);
   

3. Custom Twig Filters: Extend default rendering:

   {{ pagination|oka_pagination({
       'template': '@MyBundle/Pagination/custom.html.twig',
       'pageParameter': 'custom_page'
   }) }}
   

4. Event Listeners: Subscribe to oka_pagination.build to modify pagination logic:

   // src/EventListener/PaginationListener.php
   public function onBuild(PaginationEvent $event) {
       $event->setItemsPerPage($event->getItemsPerPage() * 2); // Double items per page
   }
   

   Register in services.yaml:

   services:
       App\EventListener\PaginationListener:
           tags:
               - { name: kernel.event_listener, event: oka_pagination.build }
   

5. API Responses: Serialize pagination metadata:

   return $this->json([
       'data' => $pagination->getItems(),
       'meta' => [
           'current_page' => $pagination->getCurrentPage(),
           'total_pages' => $pagination->getTotalPages(),
       ]
   ]);
   

Integration Tips

• Doctrine ORM: Works seamlessly with QueryBuilder (supports DQL).
• API Platform: Use PaginationEvent to inject pagination into collections.
• Symfony Forms: Bind pagination parameters to form fields for dynamic filtering.
• Caching: Cache QueryBuilder results if pagination is static (e.g., product listings).

Gotchas and Tips

Pitfalls

1. QueryBuilder Modification:

   • Avoid modifying the QueryBuilder after passing it to paginate(). The bundle clones it internally, but side effects (e.g., ->orderBy()) may persist.
   • Fix: Use a fresh QueryBuilder or reset it:

     $qb = $entityManager->getRepository(MyEntity::class)->createQueryBuilder('e');
     $qb->resetDQLPart('orderBy'); // Reset if needed
     

2. Twig Template Overrides:

   • Overriding templates requires proper namespace resolution. Ensure your template path is registered in twig.config.paths.
   • Debug: Check var/log/dev.log for missing template errors.

3. Pagination Events:

   • Events fire before pagination logic runs. Modify $event->getQueryBuilder() to alter queries.
   • Common Mistake: Forgetting to call $event->setQueryBuilder() after modifications.

4. Array Pagination Limits:

   • paginateArray() does not support QueryBuilder features (e.g., COUNT queries). Use only for in-memory data.

5. Performance:

   • For large datasets, ensure your QueryBuilder uses SELECT only needed fields (avoid SELECT *).
   • Tip: Use ->setMaxResults() and ->setFirstResult() manually for fine-grained control.

Debugging

1. Log Pagination Data:

   $this->logger->debug('Pagination', [
       'items' => count($pagination->getItems()),
       'total' => $pagination->getTotalItems(),
       'query' => $pagination->getQueryBuilder()->getDQL(),
   ]);
   

2. Check Event Dispatching: Enable Symfony’s event dispatcher debug:

   $this->container->get('debug.stopwatch')->check('pagination');
   

3. Validate Twig Templates: Use {{ dump(pagination) }} to inspect the object structure in templates.

Extension Points

1. Custom Pagination Classes: Extend CedrickOka\PaginationBundle\Pagination\Pagination to add methods:

   class MyCustomPagination extends Pagination {
       public function getFilteredItems() {
           return array_filter($this->items, fn($item) => $item->isActive());
       }
   }
   

   Register as a service:

   services:
       App\Pagination\MyCustomPagination:
           parent: oka_pagination.pagination
           tags: ['oka_pagination.pagination']
   

2. Dynamic Items Per Page: Use a Request parameter:

   $limit = $request->query->getInt('per_page', 10);
   $pagination = $paginator->paginate($qb, $page, $limit);
   

3. Localization: Override translation keys in config/packages/oka_pagination.yaml:

   oka_pagination:
       templates:
           pagination: '@MyBundle/Pagination/custom.html.twig'
       translation:
           previous: '« Anterior'
           next: 'Siguiente »'
   

4. AJAX Support: Render only pagination links for AJAX:

   {% if request.isXmlHttpRequest %}
       {{ pagination|oka_pagination({'template': '@OkaPagination/pagination_links.html.twig'}) }}
   {% endif %}