Paginator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ecommit/paginator
   

   Add the namespace to your composer.json autoload or use it directly in your code.

2. First Use Case: Paginate an array of results in a controller or service:

   use Ecommit\Paginator\ArrayPaginator;
   
   $data = ['item1', 'item2', ..., 'item1000'];
   $paginator = new ArrayPaginator([
       'page' => request('page', 1),
       'max_per_page' => 20,
       'data' => $data,
   ]);
   

3. Where to Look First:

   • ArrayPaginator class: Core implementation for array-based pagination.
   • PaginatorInterface: API contract for methods like getLastPage(), getCurrentPage(), and iteration.
   • README’s "Available options" table: Clarifies how to configure pagination behavior.

Implementation Patterns

Common Workflows

1. Basic Array Pagination:

   $paginator = new ArrayPaginator([
       'page' => $request->input('page', 1),
       'max_per_page' => 15,
       'data' => $yourArrayData,
   ]);
   

   • Use foreach ($paginator as $item) to iterate over the current page’s items.
   • Access metadata via $paginator->getLastPage() or $paginator->getCurrentPage().

2. Large Datasets (Lazy Loading):

   • Use the count option to optimize memory for large datasets:

     $paginator = new ArrayPaginator([
         'page' => 2,
         'max_per_page' => 10,
         'count' => 1000, // Total items (e.g., from DB count)
         'data' => $currentPageItems, // Only items for page 2
     ]);
     

   • Ideal for APIs or admin panels where fetching all data upfront is inefficient.

3. Integration with Laravel Views:

   • Pass the paginator to a Blade view and use it with Laravel’s built-in pagination helpers:

     return view('results', [
         'paginator' => $paginator,
     ]);
     

   • In Blade:

     {{ $paginator->appends(request()->query())->links() }}
     

     (Note: Extend the package or wrap it in a Laravel-specific trait for full compatibility.)

4. Dynamic Pagination in APIs:

   • Return paginated data as JSON:

     return response()->json([
         'data' => iterator_to_array($paginator),
         'meta' => [
             'current_page' => $paginator->getCurrentPage(),
             'last_page' => $paginator->getLastPage(),
             'per_page' => $paginator->getMaxPerPage(),
         ],
     ]);
     

5. Custom Iterators:

   • Use ArrayIterator for non-array data sources (e.g., database cursors):

     $iterator = new \ArrayIterator($yourData);
     $paginator = new ArrayPaginator([
         'data' => $iterator,
         'max_per_page' => 25,
     ]);
     

Gotchas and Tips

Pitfalls

1. count vs. data Mismatch:

   • If count is provided, data must only contain items for the current page. Passing all data will break pagination logic.
   • Example of incorrect usage:

     $paginator = new ArrayPaginator([
         'count' => 1000,
         'data' => $allItems, // ❌ Wrong: `data` should only be page 1's items.
     ]);
     

2. Zero-Based vs. One-Based Pages:

   • The package uses 1-based indexing (e.g., page=1 is the first page). Ensure your frontend/backend aligns with this.

3. Empty Data Handling:

   • If data is empty, the paginator will return an empty iterator. Validate input to avoid edge cases like:

     if (empty($paginator->getData())) {
         return response()->json(['error' => 'No data found']);
     }
     

4. Performance with Large data:

   • Avoid passing massive arrays to data when count is not used. The package loads all data into memory for pagination calculations.

5. No Built-in Laravel Integration:

   • Unlike Laravel’s native paginator, this package lacks:
     • Automatic query builder integration.
     • Blade directive support (e.g., @foreach ($paginator as $item)).
   • Workaround: Wrap the paginator in a Laravel-specific service or trait.

Debugging Tips

1. Verify count and data:

   • Log the values to ensure they match expectations:

     \Log::debug('Paginator count:', [$paginator->getCount(), count($paginator->getData())]);
     

2. Check Page Bounds:

   • If page exceeds getLastPage(), the paginator returns an empty iterator. Handle this gracefully:

     if ($paginator->getCurrentPage() > $paginator->getLastPage()) {
         abort(404, 'Page not found');
     }
     

3. Iterator Issues:

   • If using ArrayIterator, ensure it’s not modified externally during pagination (e.g., by another loop).

Extension Points

1. Custom Paginator Classes:

   • Implement PaginatorInterface to create domain-specific paginators (e.g., for APIs or admin panels).

2. Add Laravel Compatibility:

   • Extend ArrayPaginator to support Laravel’s Illuminate\Pagination\LengthAwarePaginator interface:

     class LaravelPaginator extends ArrayPaginator implements LengthAwarePaginator
     {
         public function getCollection() { /* ... */ }
         public function getUrl($page) { /* ... */ }
     }
     

3. Caching:

   • Cache paginated results for static data (e.g., product listings):

     $cacheKey = "paginator_{$request->page}_{$request->category}";
     return Cache::remember($cacheKey, now()->addHours(1), function () use ($request, $data) {
         return new ArrayPaginator([...]);
     });
     

4. Event Hooks:

   • Add events (e.g., PaginatorCreated) to log or modify paginator behavior:

     event(new PaginatorCreated($paginator));
     

Configuration Quirks

• Default Values:
  • max_per_page defaults to 100, which may be too high for APIs. Override it per request:

    $paginator = new ArrayPaginator([
        'max_per_page' => $request->input('per_page', 10), // Default to 10
    ]);
    

• Case Sensitivity:
  • Option names in the constructor are case-sensitive (e.g., 'max_per_page' vs. 'MaxPerPage').