Doctrine Paginator Decorator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cethyworks/doctrine-paginator-decorator
   

   Add to composer.json under require if not using autoload.

2. First Use Case: Replace raw Doctrine Paginator with the decorator in a repository/service:

   use Cethyworks\DoctrinePaginatorDecorator\DoctrinePaginatorDecorator;
   
   $queryBuilder = $entityManager->createQueryBuilder()
       ->select('u')
       ->from('App\Entity\User', 'u');
   
   $paginator = new DoctrinePaginatorDecorator($queryBuilder, $currentPage, $limitPerPage);
   

3. Key Methods to Explore:

   • getList() → Fetch paginated entities.
   • getCount() → Get total records (avoids COUNT queries in some cases).
   • hasNextPage() → Check for pagination bounds.

Implementation Patterns

Workflow Integration

1. Repository Layer: Wrap Doctrine Paginator in a repository method:

   public function paginateUsers(int $page, int $limit): array
   {
       $qb = $this->createQueryBuilder('u');
       $paginator = new DoctrinePaginatorDecorator($qb, $page, $limit);
       return [
           'data' => $paginator->getList(),
           'meta' => [
               'total' => $paginator->getCount(),
               'pages' => ceil($paginator->getCount() / $limit),
           ],
       ];
   }
   

2. API Controller: Use with Laravel’s Illuminate\Pagination\LengthAwarePaginator for consistency:

   $items = $paginator->getList();
   $total = $paginator->getCount();
   return new LengthAwarePaginator(
       $items,
       $total,
       $paginator->getLimit(),
       $currentPage,
       ['path' => request()->url()]
   );
   

3. Dynamic Query Building: Chain QueryBuilder methods before passing to the decorator:

   $qb = $this->createQueryBuilder('u')
       ->where('u.active = :active')
       ->setParameter('active', true);
   
   $paginator = new DoctrinePaginatorDecorator($qb, $page, 10);
   

Performance Tips

• Avoid getCount() for Large Datasets: Use getTotalItemCount() from the underlying Paginator if the decorator’s getCount() triggers a full count query.
• Cache Results: Store paginated results in Redis if the same queries repeat.

Gotchas and Tips

Pitfalls

1. Archived Package:

   • No active maintenance; test thoroughly in production.
   • Consider forking if critical bugs arise (e.g., Doctrine 2.10+ compatibility).

2. Method Overrides:

   • getCount() may not optimize like Doctrine’s native getTotalItemCount(). Verify with EXPLAIN in your DB.

3. Pagination Edge Cases:

   • hasNextPage() returns false for empty pages, but getList() returns an empty array. Handle UI rendering accordingly.

Debugging

• Query Inspection: Use Doctrine’s QueryBuilder logging to verify generated SQL:

  $qb->getQuery()->getSQL(); // Check the actual query
  

• Decorator Internals: If methods return unexpected results, inspect the underlying Paginator:

  $paginator->getPaginator()->getIterator(); // Raw Doctrine Paginator
  

Extension Points

1. Custom Decorators: Extend the class to add methods (e.g., getPreviousPageUrl()):

   class CustomPaginator extends DoctrinePaginatorDecorator {
       public function getPreviousPageUrl(): ?string
       {
           return $this->getPage() > 1
               ? route('users.index', ['page' => $this->getPage() - 1])
               : null;
       }
   }
   

2. Laravel Integration: Override the decorator’s getList() to return Laravel collections:

   $paginator->getList()->map(fn($item) => new UserResource($item));
   

3. Configuration: No config file exists; pass all logic via constructor or dependency injection.