PHPackages                             lampager/lampager-cakephp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. lampager/lampager-cakephp

ActiveCakephp-plugin[Utility & Helpers](/categories/utility)

lampager/lampager-cakephp
=========================

Rapid pagination for CakePHP 5

v3.1.1(11mo ago)731.2k3[1 issues](https://github.com/lampager/lampager-cakephp/issues)MITPHPPHP ^8.1CI failing

Since Jan 1Pushed 11mo ago8 watchersCompare

[ Source](https://github.com/lampager/lampager-cakephp)[ Packagist](https://packagist.org/packages/lampager/lampager-cakephp)[ RSS](/packages/lampager-lampager-cakephp/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (4)Versions (21)Used By (0)

[![lampager-cakephp](https://user-images.githubusercontent.com/1351893/31820647-42c45c7a-b5dd-11e7-9ac8-f1000e961662.png)](https://user-images.githubusercontent.com/1351893/31820647-42c45c7a-b5dd-11e7-9ac8-f1000e961662.png)

[![CI Workflow](https://github.com/lampager/lampager-cakephp/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/lampager/lampager-cakephp/actions/workflows/ci.yml?query=branch:master)[![Coverage Status](https://camo.githubusercontent.com/0becf40fb4dbff1c0906205554936642798fbf3ad4d350a3787257988405bfec/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6c616d70616765722f6c616d70616765722d63616b657068702f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/lampager/lampager-cakephp?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/2d23bd250c5a3ac1b1a7df7e86e8f5e4d19a58341db78e7ac932ce308878d0fd/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c616d70616765722f6c616d70616765722d63616b657068702f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/lampager/lampager-cakephp/?branch=master)

Lampager for CakePHP
====================

[](#lampager-for-cakephp)

Rapid pagination without using OFFSET

Requirements
------------

[](#requirements)

- PHP: ^8.1
- CakePHP: ^5.1
- [lampager/lampager](https://github.com/lampager/lampager): ^0.4

### Note

[](#note)

- For CakePHP 2.x, use [lampager/lampager-cakephp2](https://github.com/lampager/lampager-cakephp2).
- For CakePHP 3.x, use [lampager/lampager-cakephp v1.x](https://github.com/lampager/lampager-cakephp/tree/v1.x).
- For CakePHP 4.x, use [lampager/lampager-cakephp v2.x](https://github.com/lampager/lampager-cakephp/tree/v2.x).
- For CakePHP 5.x, use lampager/lampager-cakephp v3.x (this version).

Installing
----------

[](#installing)

```
composer require lampager/lampager-cakephp:^3.0
```

For SQLite users, see [SQLite](#sqlite) to configure.

Basic Usage
-----------

[](#basic-usage)

Simply install as a Composer package and use in one or more of the following methods:

- Use in Controller (via `\Lampager\Cake\Datasource\Paginator`)
- Use in Table (via `\Lampager\Cake\Model\Behavior\LampagerBehavior`)

### Use in Controller

[](#use-in-controller)

At first, configure `$paginate` to use `\Lampager\Cake\Datasource\Paginator` in your Controller class.

```
namespace App\Controller;

use Cake\Controller\Controller;
use Lampager\Cake\Datasource\Paginator;

class AppController extends Controller
{
    public $paginate = [
        'className' => Paginator::class,
    ];
}
```

Use in a way described in the Cookbook: [Pagination](https://book.cakephp.org/5/en/controllers/pagination.html). Note the options that are specific to Lampager such as `forward`, `seekable`, or `cursor`.

```
$query = $this->Posts
    ->where(['Posts.type' => 'public'])
    ->orderByDesc('created')
    ->orderByDesc('id')
    ->limit(10);

$posts = $this->paginate($query, [
    'forward' => true,
    'seekable' => true,
    'cursor' => [
        'id' => 4,
        'created' => '2020-01-01 10:00:00',
    ],
]);

$this->set('posts', $posts);
```

### Use in Table

[](#use-in-table)

Initialize `LampagerBehavior` in your Table class (`AppTable` is preferable) and simply use `lampager()` there.

```
namespace App\Model\Table;

use Cake\ORM\Table;
use Lampager\Cake\Model\Behavior\LampagerBehavior;

class AppTable extends Table
{
    public function initialize(array $config): void
    {
        parent::initialize($config);

        $this->addBehavior(LampagerBehavior::class);
    }
}
```

The query builder (`\Lampager\Cake\ORM\Query`) extends the plain old `\Cake\ORM\Query` and is mixed in with `\Lampager\Paginator`. Note that some of the methods in `\Lampager\Paginator`, viz., `orderBy()`, `orderByDesc()`, and `clearOrderBy()` are not exposed because their method signatures are not compatible with the CakePHP query builder.

```
$cursor = [
    'id' => 4,
    'created' => '2020-01-01 10:00:00',
    'modified' => '2020-01-01 12:00:00',
];

/** @var \Lampager\Cake\PaginationResult $latest */
$latest = $this->lampager()
    ->forward()
    ->seekable()
    ->cursor($cursor)
    ->limit(10)
    ->orderByDesc('Posts.modified')
    ->orderByDesc('Posts.created')
    ->orderByDesc('Posts.id')
    ->paginate();

foreach ($latest as $post) {
    /** @var \Cake\ORM\Entity $post */
    debug($post->id);
    debug($post->created);
    debug($post->modified);
}
```

The methods from the CakePHP query builder, e.g., `where()`, are available. `\Cake\Database\Expression\QueryExpression` is accepted as well.

```
/** @var \Lampager\Cake\PaginationResult $drafts */
$drafts = $this->lampager()
    ->where(['type' => 'draft'])
    ->forward()
    ->seekable()
    ->cursor($cursor)
    ->limit(10)
    ->orderByDesc($this->selectQuery()->newExpr('modified'))
    ->orderByDesc($this->selectQuery()->newExpr('created'))
    ->orderByDesc($this->selectQuery()->newExpr('id'))
    ->paginate();

/** @var \Cake\ORM\Entity $sample */
$sample = $drafts->sample();

/** @var int $count */
$count = $drafts->count();
```

Classes
-------

[](#classes)

See also: [lampager/lampager](https://github.com/lampager/lampager).

NameTypeParent Class
Implemented InterfaceDescriptionLampager\\Cake\\ORM\\`Query`ClassCake\\ORM\\`Query`Fluent factory implementation for CakePHPLampager\\Cake\\Model\\Behavior\\`LampagerBehavior`ClassCake\\ORM\\`Behavior`CakePHP behavior which returns Lampager\\Cake\\ORM\\`Query`Lampager\\Cake\\Datasource\\`Paginator`ClassCake\\Datasource\\`Paginator`CakePHP paginatior which delegates to Lampager\\Cake\\ORM\\`Query`Lampager\\Cake\\`Paginator`ClassLampager\\`Paginator`Paginator implementation for CakePHPLampager\\Cake\\`ArrayProcessor`ClassLampager\\`ArrayProcessor`Processor implementation for CakePHPLampager\\Cake\\`PaginationResult`ClassLampager\\`PaginationResult`
Cake\\Datasource\\Paging\\`PaginatedInterface`PaginationResult implementation for CakePHPLampager\\Cake\\Database\\`SqliteCompiler`ClassCake\\Database\\`QueryCompiler`Query compiler implementation for SQLiteLampager\\Cake\\Database\\Driver\\`Sqlite`ClassCake\\Database\\Driver\\`Sqlite`Driver implementation which delegates to Lampager\\Cake\\Database\\`SqliteCompiler`API
---

[](#api)

See also: [lampager/lampager](https://github.com/lampager/lampager).

### LampagerBehavior::lampager()

[](#lampagerbehaviorlampager)

Build a Lampager query from Table in exactly the same way as CakePHP.

```
LampagerBehavior::lampager(): \Lampager\Cake\ORM\Query
```

### Paginator::\_\_construct()
Paginator::create()

[](#paginator__constructpaginatorcreate)

Create a new paginator instance. These methods are not intended to be directly used in your code.

```
static Paginator::create(\Cake\ORM\Query\SelectQuery $builder): static
Paginator::__construct(\Cake\ORM\Query\SelectQuery $builder)
```

### Paginator::transform()

[](#paginatortransform)

Transform a Lampager query into a CakePHP query.

```
Paginator::transform(\Lampager\Query $query): \Cake\ORM\Query\SelectQuery
```

### Paginator::build()

[](#paginatorbuild)

Perform configure + transform.

```
Paginator::build(\Lampager\Contracts\Cursor|array $cursor = []): \Cake\ORM\Query\SelectQuery
```

### Paginator::paginate()

[](#paginatorpaginate)

Perform configure + transform + process.

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

#### Arguments

[](#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 the initial page, omit this parameter or pass an empty array.
    - For the subsequent pages, pass all the parameters. The partial one is not allowed.

#### Return Value

[](#return-value)

e.g.,

(Default format when using `\Cake\ORM\Query`)

```
object(Lampager\Cake\PaginationResult)#1 (6) {
  ["(help)"]=>
  string(44) "This is a Lampager Pagination Result object."
  ["records"]=>
  array(3) {
    [0]=>
    object(Cake\ORM\Entity)#2 (11) { ... }
    [1]=>
    object(Cake\ORM\Entity)#3 (11) { ... }
    [2]=>
    object(Cake\ORM\Entity)#4 (11) { ... }
  ["hasPrevious"]=>
  bool(false)
  ["previousCursor"]=>
  NULL
  ["hasNext"]=>
  bool(true)
  ["nextCursor"]=>
  array(2) {
    ["created"]=>
    object(Cake\I18n\Time)#5 (3) {
      ["date"]=>
      string(26) "2017-01-01 10:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }
    ["id"]=>
    int(1)
  }
}
```

### PaginationResult::\_\_call()

[](#paginationresult__call)

`\Lampager\Cake\PaginationResult` implements `\Cake\Datasource\Paging\PaginatedInterface`.

Examples
--------

[](#examples)

This section describes the practical usage of lampager-cakephp.

### Use in Controller

[](#use-in-controller-1)

The example below shows how to accept a cursor parameter from a request and pass it through `PaginatorComponent::paginate()`. Be sure that your `AppController`has properly initialized `Paginator` as above.

```
namespace App\Controller;

class PostsController extends AppController
{
    public $Posts = null;

    /**
     * This method shows how to pass options by a query and array.
     */
    public function query(): void
    {
        // Get cursor parameters
        $previous = json_decode($this->request->getQuery('previous_cursor'), true);
        $next = json_decode($this->request->getQuery('next_cursor'), true);
        $cursor = $previous ?: $next ?: [];

        // Query expression can be passed to PaginatorComponent::paginate() as normal
        $query = $this->Posts
            ->where(['Posts.type' => 'public'])
            ->orderByDesc('created')
            ->orderByDesc('id')
            ->limit(15);

        /** @var \Lampager\Cake\PaginationResult $posts */
        $posts = $this->paginate($query, [
            // If the previous_cursor is not set, paginate forward; otherwise backward
            'forward' => !$previous,
            'cursor' => $cursor,
            'seekable' => true,
        ]);

        $this->set('posts', $posts);
    }

    /**
     * This method shows how to pass options from an array.
     */
    public function options(): void
    {
        // Get cursor parameters
        $previous = json_decode($this->request->getQuery('previous_cursor'), true);
        $next = json_decode($this->request->getQuery('next_cursor'), true);
        $cursor = $previous ?: $next ?: [];

        /** @var \Lampager\Cake\PaginationResult $posts */
        $posts = $this->paginate('Posts', [
            // Lampager options
            // If the previous_cursor is not set, paginate forward; otherwise backward
            'forward' => !$previous,
            'cursor' => $cursor,
            'seekable' => true,

            // PaginatorComponent config
            'conditions' => [
                'type' => 'public',
            ],
            'order' => [
                'created' => 'DESC',
                'id' => 'DESC',
            ],
            'limit' => 15,
        ]);

        $this->set('posts', $posts);
    }
}
```

And the pagination links can be output as follows:

```
// If there is a next page, print pagination link
if ($posts->hasPrevious) {
    echo $this->Html->link('>', [
        'controller' => 'posts',
        'action' => 'index',
        '?' => [
            'next_cursor' => json_encode($posts->nextCursor),
        ],
    ]);
}
```

Supported database engines
--------------------------

[](#supported-database-engines)

### MySQL, MariaDB, and PostgreSQL

[](#mysql-mariadb-and-postgresql)

Supported!

### Microsoft SQL Server

[](#microsoft-sql-server)

Not supported.

### SQLite

[](#sqlite)

Supported but requires an additional configuration.

In SQLite `UNION ALL` statements cannot combine `SELECT` statements that have `ORDER BY` clause. In order to get this to work, those `SELECT` statements have to be wrapped by a subquery like `SELECT * FROM (...)`. CakePHP not natively handling this situation, Lampager for CakePHP introduces `\Lampager\Cake\Database\Driver\Sqlite` that needs to be installed on your application. Configure like the following in your `config/app.php`:

```
return [
    'Datasources' => [
        'default' => [
            'className' => Connection::class,
            'driver' => \Lampager\Cake\Database\Driver\Sqlite::class,
            'username' => '********',
            'password' => '********',
            'database' => '********',
        ],
    ],
];
```

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance48

Moderate activity, may be stable

Popularity33

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 92.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~108 days

Recently: every ~122 days

Total

20

Last Release

348d ago

Major Versions

v1.0.3 → v2.1.02021-01-21

v1.1.0 → v2.3.02023-03-16

v1.x-dev → v2.4.02024-04-12

v2.4.0 → v3.0.02024-04-21

v2.x-dev → v3.1.12025-08-24

PHP version history (5 changes)v0.1.0PHP ^5.6 || ^7.0

v2.0.0PHP ^7.2

v2.1.0PHP ^7.2 || ^8.0

v2.3.0PHP ^7.4 || ^8.0

v3.0.0PHP ^8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6535425?v=4)[Chitoku](/maintainers/chitoku-k)[@chitoku-k](https://github.com/chitoku-k)

---

Top Contributors

[![chitoku-k](https://avatars.githubusercontent.com/u/6535425?v=4)](https://github.com/chitoku-k "chitoku-k (39 commits)")[![dakota](https://avatars.githubusercontent.com/u/83255?v=4)](https://github.com/dakota "dakota (1 commits)")[![kewlburn](https://avatars.githubusercontent.com/u/206205?v=4)](https://github.com/kewlburn "kewlburn (1 commits)")[![scrutinizer-auto-fixer](https://avatars.githubusercontent.com/u/6253494?v=4)](https://github.com/scrutinizer-auto-fixer "scrutinizer-auto-fixer (1 commits)")

---

Tags

cakephpcakephp-pluginfastpaginationpaginatorphppaginatorpaginationcakephplimitoffset

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/lampager-lampager-cakephp/health.svg)

```
[![Health](https://phpackages.com/badges/lampager-lampager-cakephp/health.svg)](https://phpackages.com/packages/lampager-lampager-cakephp)
```

###  Alternatives

[dereuromark/cakephp-tools

A CakePHP plugin containing lots of useful and reusable tools

3351.0M51](/packages/dereuromark-cakephp-tools)[lampager/lampager-laravel

Rapid pagination for Laravel

7643.3k](/packages/lampager-lampager-laravel)[cakephp/bake

Bake plugin for CakePHP

11212.2M217](/packages/cakephp-bake)[dereuromark/cakephp-ide-helper

CakePHP IdeHelper Plugin to improve auto-completion

1892.4M46](/packages/dereuromark-cakephp-ide-helper)[lampager/lampager

Rapid pagination without using OFFSET

3781.8k6](/packages/lampager-lampager)[jasongrimes/paginator

A lightweight PHP paginator, for generating pagination controls in the style of Stack Overflow and Flickr. The 'first' and 'last' page links are shown inline as page numbers, and excess page numbers are replaced by ellipses.

4071.3M22](/packages/jasongrimes-paginator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)