younes_mlik/hybrid-pagination

Hybrid pagination for Laravel.

v0.0.1 2025-04-23 18:36 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.41
• illuminate/database: ^11.41
• illuminate/http: ^11.41
• illuminate/pagination: ^11.41
• illuminate/support: ^11.41

MIT

• Younes Mlik

• database
• pagination
• laravel
• illuminate
• eloquent

README

Hybrid Pagination is a scalable pagination solution that enhances Laravel’s Eloquent ORM by combining the convenience of offset-based with the performance of cursor-based pagination. This allows:

• Direct page jumps (offset-style navigation)

• Efficient handling of large datasets (cursor-based optimization)

• Significantly lower database expense

Unlike traditional pagination methods, Hybrid Pagination provides random page access without sacrificing performance.

Features

✅ Fluent API similar to Laravel’s built-in pagination.
✅ Works with Eloquent – Supports complex queries and relationships.
✅ Optimized for Large Datasets – Avoids deep offset performance issues.
✅ Customizable Navigation – Configure cursor fields, page names, and total count behavior.

Installation

composer require younes_mlik/hybrid-pagination

Usage

Basic Usage

namespace App\Models;

use App\Traits\CanHybridPaginate;

class User extends Model
{
    use CanHybridPaginate;

    ...

$users = User::
    orderBy("first_name")->
    orderBy("id")->
    hybridPaginate(4, "*");

Configuration

You can publish the configuration file:

php artisan vendor:publish --tag=hybrid-pagination-config

Config file (config/hybrid_pagination.php):

return [
    'default_cursor_field' => 'id',
    'threshold' => 1000, // Switch to cursor pagination when offset exceeds this value
];

Why Use Hybrid Pagination?

Feature	Offset Pagination	Cursor Pagination	Hybrid Pagination
Random page access	✅	❌	✅
Performance on large datasets	❌	✅	✅

License

This package is open-sourced software licensed under the MIT license.