Pagination Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cannibal/pagination-bundle
   

   Add to config/app.php under providers:

   Cannibal\PaginationBundle\PaginationBundle::class,
   

2. First Use Case: Paginate a simple Eloquent collection:

   use Cannibal\PaginationBundle\Pagination;
   
   $items = Item::all();
   $paginated = Pagination::make($items, 10); // 10 items per page
   return view('items.index', compact('paginated'));
   

3. Where to Look First:

   • Service Provider: src/PaginationBundle/PaginationBundle.php for core logic.
   • Facade: app/Pagination.php for quick access.
   • View Helpers: Check resources/views/vendor/pagination for default templates.

Implementation Patterns

Core Workflows

1. Basic Pagination:

   $paginated = Pagination::make($collection, $perPage);
   

   • Works with Eloquent, arrays, or any Arrayable/Jsonable objects.

2. URL-Based Pagination:

   $paginated = Pagination::make($collection, $perPage, request('page', 1));
   

   • Automatically respects ?page=N query params.

3. Custom Views: Override default templates by publishing assets:

   php artisan vendor:publish --tag=pagination.views
   

   Modify files in resources/views/vendor/pagination.

4. API Responses:

   return response()->json($paginated->toArray());
   

   Returns standardized JSON with data, meta (pagination info), and links.

5. Dynamic Per-Page:

   $perPage = request('per_page', 10);
   $paginated = Pagination::make($collection, $perPage);
   

Integration Tips

• Laravel Scout: Use toArray() for search results:

  $searchResults = Item::search('query')->paginate(15);
  return Pagination::make($searchResults->items(), 15)->toArray();
  

• Livewire/Alpine: Bind paginated object directly to components for reactive updates.
• Testing: Mock Pagination facade for unit tests:

  $this->partialMock(Pagination::class, function ($mock) {
      $mock->shouldReceive('make')->andReturn($mock->makePartial());
  });
  

Gotchas and Tips

Pitfalls

1. Query String Conflicts:

   • If using route() in links, ensure page param doesn’t clash with existing query strings.
   • Fix: Use ?page={$paginated->currentPage} explicitly.

2. Arrayable Objects:

   • Non-Eloquent collections (e.g., API responses) must implement Arrayable or Jsonable.
   • Fix: Wrap in collect() or use toArray() manually.

3. Caching:

   • Paginated results aren’t cached by default. For large datasets, cache the base query:

     $cachedItems = Cache::remember("items_{$perPage}", now()->addHours(1), function() use ($perPage) {
         return Item::paginate($perPage);
     });
     

4. Bootstrap CSS Dependency:

   • Default templates assume Bootstrap. For Tailwind/other CSS, override templates or use bootstrap: false in config:

     'templates' => [
         'bootstrap' => false,
     ],
     

Debugging

• Log Pagination Data:

  \Log::debug('Pagination meta:', $paginated->meta());
  

• Check Config:

  php artisan config:clear
  

  If pagination links break after updates.

Extension Points

1. Custom Meta Data: Add extra metadata to the meta array:

   $paginated->withMeta(['custom_key' => 'value']);
   

2. Link Generators: Override link generation for non-route-based URLs:

   Pagination::macro('generateUrl', function ($page) {
       return url("custom/path?page=$page");
   });
   

3. Event Listeners: Listen for pagination events (e.g., PaginationGenerated):

   Pagination::addListener(function ($paginated) {
       // Modify $paginated before rendering
   });
   

4. Localization: Override labels (e.g., "Previous", "Next") via config:

   'labels' => [
       'previous' => 'Prev',
       'next' => 'Next',
   ],