Pagination Laravel Package

Getting Started

Install via composer require illuminate/pagination. While this is a standalone package, it's officially intended for use within Laravel (v13+) — installing laravel/framework will include it automatically. For non-Laravel usage, manually bootstrap the Illuminate container and register PaginationServiceProvider. Start with a basic example using the Query Builder:

use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Facades\DB;

$page = LengthAwarePaginator::resolveCurrentPage();
$items = DB::table('posts')->paginate(10, ['*'], 'page', $page);
// Or: DB::table('posts')->paginate(10); // Laravel context auto-detects current page

Implementation Patterns

• Eloquent / Query Builder Pagination: Use ->paginate(15) or ->simplePaginate(15) for offset-based; ->cursorPaginate(15) for cursor-based. Laravel injects results directly into views as LengthAwarePaginator instances.
• Blade Rendering: In Blade templates, render pagination links with {{ $items->links() }} (defaults to Bootstrap 5). Customize via links('pagination::tailwind') or custom views (e.g., links('vendor.pagination.my-theme')).
• API Responses: Return paginated JSON: return response()->json($items->items()); and include meta via ->response()->getData(true). For cursor pagination, use Cursor::fromEncoded($cursorString) to decode next/prev URLs.
• Custom Presenters: Extend BootstrapFourPaginator, BootstrapThreePaginator, or implement Paginator interface to fully customize HTML generation (e.g., Tailwind CSS, React-compatible output).
• Manual Pagination: For non-standard flows (CLI, custom routing), instantiate manually:

  new LengthAwarePaginator(
    $items,
    $total,
    $perPage,
    $currentPage,
    ['path' => '/custom/path', 'query' => ['filter' => 'active']]
  );
  

Gotchas and Tips

• Standalone ≠ Production-Ready Outside Laravel: Though published separately, this package depends on other illuminate/* packages (collections, contracts, support) and assumes Laravel’s service container, URL generator, and HTTP context. Manually resolving it in non-Laravel apps risks silent failures or version skew.
• PHP 8.3+ Only: No support for older PHP versions — avoid in legacy systems unless upgrading.
• Path/URL Resolution Breaks Outside Laravel: Paginator::resolveCurrentPath() and url() helpers won’t work. Manually set path() or use parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) + custom URL generation.
• Cursor Pagination Requires Unique Columns: cursorPaginate() needs a database column that’s unique, non-decreasing, and stable (e.g., created_at + id). Updates to these columns mid-pagination cause duplicates or skipped records.
• Testing Pitfalls: In unit tests, avoid ->paginate() (triggers DB calls). Instead, mock LengthAwarePaginator or use Collection::forPage() for isolated logic tests.
• Extensibility Hooks: Override view components by publishing Laravel’s pagination views (when using full framework) or injecting custom renderers via view()->make('custom-view', ['paginator' => $paginator]).
• Query String Pitfalls: Default pagination preserves all query params. Use ->withQuery([]) or ->appends(['key' => 'value']) to control URL parameters — forgetting this can break filters/sorting.