Lampager for CakePHP 2

Rapid pagination without using OFFSET

Requirements

• PHP: ^5.6 || ^7.0
• CakePHP: ^2.10
• lampager/lampager: ^0.4

Note

• For CakePHP 2.x, use lampager/lampager-cakephp2 (this version).
• For CakePHP 3.x, use lampager/lampager-cakephp v1.x.
• For CakePHP 4.x, use lampager/lampager-cakephp v2.x.

Installing

composer require lampager/lampager-cakephp2

Move Plugin/Lampager to the appropriate directory if necessary.

Basic Usage

Load as a plugin. See How To Install Plugins for detail.

Plugin needs to be loaded manually in app/Config/bootstrap.php:

// Be sure to require vendor/autoload.php beforehand.
// CakePlugin::load() will fail unless autoloader is properly configured.
CakePlugin::load('Lampager');

Next, add 'Lampager.Lampager' to your Model class (AppModel is preferable):

class AppModel extends Model
{
    public $actsAs = [
        'Lampager.Lampager',
    ];
}

Use in one or more of the following methods:

• Use in Controller (via LampagerBehavior)
• Use in Model (via LampagerBehavior)

Use in Controller

At first, your Model class must have 'Lampager.Lampager' enabled. Use in a way described in the Cookbook: Pagination. Note the options that are specific to Lampager such as forward, seekable, or cursor.

/** @var \Lampager\PaginationResult $posts */
$posts = $this->paginate(Post::class, [
    // Lampager options
    'forward' => true,
    'seekable' => true,
    'cursor' => [
        'Post' => [
            'id' => '4',
            'created' => '2017-01-01 10:00:00',
        ],
    ],

    // PaginatorComponent::settings query
    'conditions' => [
        'Post.type' => 'public',
    ],
    'order' => [
        'Post.created' => 'DESC',
        'Post.id' => 'DESC',
    ],
    'limit' => 10,
]);

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

Use in Model

At first, your Model class must have 'Lampager.Lampager' enabled. Simply use Model::find with lampager. The custom find type lampager (see Retrieving Your Data) works in a way similar to the core find type all with additional parameters and post processor enabled.

/** @var \Lampager\PaginationResult $posts */
$posts = $this->find('lampager', [
    // Lampager options
    'forward' => true,
    'seekable' => true,
    'cursor' => [
        'Post' => [
            'id' => '4',
            'created' => '2017-01-01 10:00:00',
        ],
    ],

    // Model::find query
    'limit' => 10,
    'order' => [
        'Post.modified' => 'DESC',
        'Post.created' => 'DESC',
        'Post.id' => 'DESC',
    ],
]);

foreach ($posts as $post) {
    /** @var mixed[][] $post */
    debug($post['Post']['id']);
    debug($post['Post']['created']);
    debug($post['Post']['modified']);
}

Classes

See also: lampager/lampager.

Name	Type	Extends	Description
LampagerBehavior	Class	ModelBehavior	CakePHP behavior which handles Model::find() and PaginatorComponent::paginate()
LampagerArrayCursor	Class	Lampager\Contracts\Cursor	Multi-dimensional array cursor
LampagerPaginator	Class	Lampager\Paginator	Paginator implementation for CakePHP
LampagerArrayProcessor	Class	Lampager\ArrayProcessor	Processor implementation for CakePHP
LampagerColumnAccess	Class		Multi-dimensional array accessor
LampagerTransformer	Class		CakePHP query genenrator

API

See also: lampager/lampager.

Using Model::find() or PaginatorComponent::paginate() is recommended. The query is merged with CakePHP query and passed to Lampager\Query.

LampagerPaginator::__construct()
LampagerPaginator::create()

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

static LampagerPaginator::create(Model $builder, array $options): static
LampagerPaginator::__construct(Model $builder, array $options)

LampagerPaginator::transform()

Transform a Lampager query into a CakePHP query.

LampagerPaginator::transform(\Lampager\Query $query): array

LampagerPaginator::build()

Perform configure + transform.

LampagerPaginator::build(array $cursor = []): array

LampagerPaginator::paginate()

Perform configure + transform + process.

LampagerPaginator::paginate(array $cursor = []): \Lampager\PaginationResult

Arguments

• (array) $cursor
  An associative array that contains $column => $value. 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

e.g.,

(Default format when using Model::find())

object(Lampager\PaginationResult)#1 (5) {
  ["records"]=>
  array(3) {
    [0]=>
    array(1) {
      ["Post"]=>
      array(3) { ... }
    }
    [1]=>
    array(1) {
      ["Post"]=>
      array(3) { ... }
    }
    [2]=>
    array(1) {
      ["Post"]=>
      array(3) { ... }
    }
  }
  ["hasPrevious"]=>
  bool(false)
  ["previousCursor"]=>
  NULL
  ["hasNext"]=>
  bool(true)
  ["nextCursor"]=>
  array(1) {
    ["Post"]=>
    array(2) {
      ["id"]=>
      string(1) "3"
      ["created"]=>
      string(19) "2017-01-01 10:00:00"
    }
  }
}

LampagerTransformer::__construct()

Create a new transformer instance. This class is not intended to be directly used in your code.

LampagerTransformer::__construct(Model $builder, array $options)

Examples

This section describes the practial usages of lampager-cakephp2.

Use in Controller

The example below shows how to accept a cursor parameter from a request and pass it through PaginatorComponent::settings. Be sure that your Model class has 'Lampager.Lampager' enabled.

class PostsController extends AppController
{
    public function index()
    {
        // Get cursor parameters
        $previous = $this->request->param('named.previous_cursor');
        $next = $this->request->param('named.next_cursor');

        $this->Paginator->settings = [
            // Lampager options
            // If the previous_cursor is not set, paginate forward; otherwise backward
            'forward' => !$previous,
            'cursor' => $previous ?: $next ?: [],
            'seekable' => true,

            // PaginatorComponent::settings query
            'conditions' => [
                'Post.type' => 'public',
            ],
            'order' => [
                'Post.created' => 'DESC',
                'Post.id' => 'DESC',
            ],
            'limit' => 10,
        ];

        /** @var \Lampager\PaginationResult $posts */
        $posts = $this->Paginator->paginate(Post::class);
        $this->set('posts', $posts);
    }
}

And the pagination links can be output as follows:

// If there is a previous page, print pagination link
if ($posts->hasPrevious) {
    echo $this->Html->link('<< Previous', [
        'controller' => 'posts',
        'action' => 'index',
        'previous_cursor' => $posts->previousCursor,
    ]);
}

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

Supported database engines

MySQL, MariaDB, PostgreSQL, and SQLite

Supported!

Microsoft SQL Server

Not supported.