lampager/lampager-laravel

Rapid pagination for Laravel

, _(*1)

<, _(*2)

p align="center"> , _(*3)

Lampager for Laravel

Rapid pagination without using OFFSET, _(*4)

[!CAUTION] Now Laravel officialy supports Cursor Pagination as of v8.41. Please don't use if you install such versions unless you choose SQLServer as RDBMS. - Highly Performant Cursor Pagination in Laravel 8.41 | Laravel News - SQL Feature Comparison (See "Tuple Comparison" section), _(*5)

Requirements

[!NOTE] Older versions have outdated dependency requirements. If you cannot prepare the latest environment, please refer to past releases., _(*6)

• PHP: ^8.2
• Laravel: ^11.0 || ^12.0
• lampager/lampager: ^0.5

Installing

composer require lampager/lampager-laravel

Basic Usage

Register service provider., _(*7)

config/app.php:, _(*8)

        /*
         * Package Service Providers...
         */
        Lampager\Laravel\MacroServiceProvider::class,

Then you can chain ->lampager() method from Query Builder, Eloquent Builder and Relation., _(*9)

$cursor = [
    'id' => 3,
    'created_at' => '2017-01-10 00:00:00',
    'updated_at' => '2017-01-20 00:00:00',
];

$result = App\Post::whereUserId(1)
    ->lampager()
    ->forward()
    ->limit(5)
    ->orderByDesc('updated_at') // ORDER BY `updated_at` DESC, `created_at` DESC, `id` DESC
    ->orderByDesc('created_at')
    ->orderByDesc('id')
    ->seekable()
    ->paginate($cursor)
    ->toJson(JSON_PRETTY_PRINT);

It will run the optimized query., _(*10)

(

    SELECT * FROM `posts`
    WHERE `user_id` = 1
    AND (
        `updated_at` = '2017-01-20 00:00:00' AND `created_at` = '2017-01-10 00:00:00' AND `id` > 3
        OR
        `updated_at` = '2017-01-20 00:00:00' AND `created_at` > '2017-01-10 00:00:00'
        OR
        `updated_at` > '2017-01-20 00:00:00'
    )
    ORDER BY `updated_at` ASC, `created_at` ASC, `id` ASC
    LIMIT 1

) UNION ALL (

    SELECT * FROM `posts`
    WHERE `user_id` = 1
    AND (
        `updated_at` = '2017-01-20 00:00:00' AND `created_at` = '2017-01-10 00:00:00' AND `id` <= 3
        OR
        `updated_at` = '2017-01-20 00:00:00' AND `created_at` < '2017-01-10 00:00:00'
        OR
        `updated_at` < '2017-01-20 00:00:00'
    )
    ORDER BY `updated_at` DESC, `created_at` DESC, `id` DESC
    LIMIT 6

)

And you'll get, _(*11)

{
  "records": [
    {
      "id": 3,
      "user_id": 1,
      "text": "foo",
      "created_at": "2017-01-10 00:00:00",
      "updated_at": "2017-01-20 00:00:00"
    },
    {
      "id": 5,
      "user_id": 1,
      "text": "bar",
      "created_at": "2017-01-05 00:00:00",
      "updated_at": "2017-01-20 00:00:00"
    },
    {
      "id": 4,
      "user_id": 1,
      "text": "baz",
      "created_at": "2017-01-05 00:00:00",
      "updated_at": "2017-01-20 00:00:00"
    },
    {
      "id": 2,
      "user_id": 1,
      "text": "qux",
      "created_at": "2017-01-17 00:00:00",
      "updated_at": "2017-01-18 00:00:00"
    },
    {
      "id": 1,
      "user_id": 1,
      "text": "quux",
      "created_at": "2017-01-16 00:00:00",
      "updated_at": "2017-01-18 00:00:00"
    }
  ],
  "has_previous": false,
  "previous_cursor": null,
  "has_next": true,
  "next_cursor": {
    "updated_at": "2017-01-18 00:00:00",
    "created_at": "2017-01-14 00:00:00",
    "id": 6
  }
}

Resource Collection

Lampager supports Laravel's API Resources., _(*12)

• Eloquent: API Resources - Laravel - The PHP Framework For Web Artisans

Use helper traits on Resource and ResourceCollection., _(*13)

use Illuminate\Http\Resources\Json\JsonResource;
use Lampager\Laravel\LampagerResourceTrait;

class PostResource extends JsonResource
{
    use LampagerResourceTrait;
}

use Illuminate\Http\Resources\Json\ResourceCollection;
use Lampager\Laravel\LampagerResourceCollectionTrait;

class PostResourceCollection extends ResourceCollection
{
    use LampagerResourceCollectionTrait;
}

$posts = App\Post::lampager()
    ->orderByDesc('id')
    ->paginate();

return new PostResourceCollection($posts);

{
  "data": [/* ... */],
  "has_previous": false,
  "previous_cursor": null,
  "has_next": true,
  "next_cursor": {/* ... */}
}

Classes

Note: See also lampager/lampager., _(*14)

Paginator, Processor and PaginationResult are macroable., _(*15)

API

Note: See also lampager/lampager., _(*16)

Paginator::__construct()
Paginator::create()

Create a new paginator instance.
If you use Laravel macros, however, you don't need to directly instantiate., _(*17)

static Paginator create(QueryBuilder|EloquentBuilder|Relation $builder): static
Paginator::__construct(QueryBuilder|EloquentBuilder|Relation $builder)

• QueryBuilder means \Illuminate\Database\Query\Builder
• EloquentBuilder means \Illuminate\Database\Eloquent\Builder
• Relation means \Illuminate\Database\Eloquent\Relation

Paginator::transform()

Transform Lampager Query into Illuminate builder., _(*18)

Paginator::transform(Query $query): QueryBuilder|EloquentBuilder|Relation

Paginator::build()

Perform configure + transform., _(*19)

Paginator::build(\Lampager\Contracts\Cursor|array $cursor = []): QueryBuilder|EloquentBuilder|Relation

Paginator::paginate()

Perform configure + transform + process., _(*20)

Paginator::paginate(\Lampager\Contracts\Cursor|array $cursor = []): \Lampager\Laravel\PaginationResult

Arguments

• (mixed) __$cursor__
  An associative array that contains $column => $value or an object that implements \Lampager\Contracts\Cursor. It must be **all-or-nothing**.
  • For initial page, omit this parameter or pass empty array.
  • For subsequent pages, pass all parameters. Partial parameters are not allowd.

Return Value

e.g., _(*21)

(Default format when using \Illuminate\Database\Eloquent\Builder), _(*22)

object(Lampager\Laravel\PaginationResult)#1 (5) {
  ["records"]=>
  object(Illuminate\Database\Eloquent\Collection)#2 (1) {
    ["items":protected]=>
    array(5) {
      [0]=>
      object(App\Post)#2 (26) { ... }
      [1]=>
      object(App\Post)#3 (26) { ... }
      [2]=>
      object(App\Post)#4 (26) { ... }
      [3]=>
      object(App\Post)#5 (26) { ... }
      [4]=>
      object(App\Post)#6 (26) { ... }
    }
  }
  ["hasPrevious"]=>
  bool(false)
  ["previousCursor"]=>
  NULL
  ["hasNext"]=>
  bool(true)
  ["nextCursor"]=>
  array(2) {
    ["updated_at"]=>
    string(19) "2017-01-18 00:00:00"
    ["created_at"]=>
    string(19) "2017-01-14 00:00:00"
    ["id"]=>
    int(6)
  }
}

Paginator::useFormatter()
Paginator::restoreFormatter()
Paginator::process()

Invoke Processor methods., _(*23)

Paginator::useFormatter(Formatter|callable $formatter): $this
Paginator::restoreFormatter(): $this
Paginator::process(\Lampager\Query $query, \Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Collection $rows): \Lampager\Laravel\PaginationResult

PaginationResult::toArray()
PaginationResult::jsonSerialize()

Convert the object into array., _(*24)

IMPORTANT: camelCase properties are converted into snake_case form., _(*25)

PaginationResult::toArray(): array
PaginationResult::jsonSerialize(): array

PaginationResult::__call()

Call macro or Collection methods., _(*26)

PaginationResult::__call(string $name, array $args): mixed

e.g., _(*27)

PaginationResult::macro('foo', function () {
    return ...;
});
$foo = $result->foo();

$first = $result->first();