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?

License

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