Paginator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dmp/paginator-bundle
   

   Add to config/app.php under providers:

   DMP\PaginatorBundle\PaginatorServiceProvider::class,
   

2. Basic Usage Inject the Paginator facade into your controller:

   use DMP\PaginatorBundle\Facades\Paginator;
   
   public function index()
   {
       $data = Model::all();
       $paginatedData = Paginator::paginate($data, 10); // 10 items per page
       return view('your.view', ['data' => $paginatedData]);
   }
   

3. Blade Integration Use the @paginate directive in your Blade template:

   @paginate($data)
   

Implementation Patterns

Common Workflows

1. Pagination with Eloquent

   $users = Paginator::paginate(User::query()->where('active', 1), 15);
   

2. Customizing Pagination Views Override default views by publishing assets:

   php artisan vendor:publish --provider="DMP\PaginatorBundle\PaginatorServiceProvider"
   

   Modify resources/views/vendor/paginator/ templates.

3. API Responses Return paginated JSON responses:

   return response()->json(Paginator::toArray($paginatedData));
   

4. Dynamic Page Size

   $pageSize = request('per_page', 10);
   $paginated = Paginator::paginate($data, $pageSize);
   

5. Integration with Livewire/Alpine

   // Livewire component
   public $perPage = 10;
   public $items;
   
   public function mount()
   {
       $this->items = Paginator::paginate(Model::all(), $this->perPage);
   }
   

Gotchas and Tips

Pitfalls

1. View Publishing Required

   • Default pagination views must be published (vendor:publish) to customize them. Forgetting this will result in blank pagination controls.

2. Query Builder vs. Collection

   • The bundle expects a query builder instance (e.g., Model::query()), not a collection (e.g., Model::all()). Passing a collection will break pagination.

3. Route Model Binding Conflicts

   • If using route model binding (e.g., Route::model('user', User::class)), ensure the paginated data doesn’t interfere with binding logic. Use Paginator::toArray() for API responses to avoid issues.

4. CSRF on Pagination Links

   • Blade pagination links may fail if CSRF protection is enabled. Add @csrf to your form or use:

     Paginator::setCsrfToken(true); // Globally enable CSRF in links
     

Debugging Tips

1. Check Pagination Data Structure Dump the paginated result to verify structure:

   dd(Paginator::paginate($data, 10)->toArray());
   

   Expected keys: data, current_page, per_page, total, last_page.

2. Log Query Builder Debug the underlying query:

   $query = User::query()->where('active', 1);
   \Log::info($query->toSql(), $query->getBindings());
   $paginated = Paginator::paginate($query, 10);
   

3. Override Default Config Publish config first:

   php artisan vendor:publish --tag=paginator-config
   

   Then modify config/paginator.php (e.g., change default_per_page).

Extension Points

1. Custom Pagination Views Extend the default views by copying vendor/dmp/paginator-bundle/resources/views to resources/views/vendor/paginator/.

2. Add Custom Data to Pagination Attach metadata to the paginator instance:

   $paginator = Paginator::paginate($data, 10);
   $paginator->with(['custom_key' => 'value']);
   

   Access in Blade:

   {{ $data->custom_key }}
   

3. Modify Pagination URLs Override the URL generator via config:

   'url_generator' => function ($paginator) {
       return route('custom.pagination.route', ['page' => $paginator->currentPage()]);
   },
   

4. Localization The bundle uses Laravel’s localization. Override translation strings in resources/lang/{locale}/paginator.php.