bcrowe/cakephp-api-pagination

CakePHP 3 plugin that injects pagination information into API responses.

CakePHP API Pagination

![Software License][ico-license] ![Coverage Status][ico-scrutinizer] ![Total Downloads][ico-downloads], _(*1)

This is a simple component for CakePHP 4.2+ which injects pagination information from CakePHP's Paginator into serialized JsonView and XmlView responses., _(*2)

See 1.x and 2.x releases and branches of this plugin for support of previous versions of CakePHP before 4.2., _(*3)

Install

Via Composer, _(*4)

``` bash $ composer require bcrowe/cakephp-api-pagination, <sub>(*5)</sub>

Load the plugin by adding `$this->addPlugin('BryanCrowe/ApiPagination');` to the `bootsrap` method in your project’s `src/Application.php`:

``` php
public function bootstrap(): void
{
    parent::bootstrap();

    // ... bootstrap code ...

    // load more plugins here

    $this->addPlugin('BryanCrowe/ApiPagination');
}

Usage

Make sure your application has been set up to use data views; see the Enabling Data Views in Your Application section of the CakePHP documentation., <sub>(*6)</sub>

Then, load ApiPaginationComponent:, <sub>(*7)</sub>

``` php $this->loadComponent('BryanCrowe/ApiPagination.ApiPagination');, <sub>(*8)</sub>

Then, go ahead and set your paginated view variable like so:

``` php
$this->set('articles', $this->paginate($this->Articles));
$this->viewBuilder()->setOption('serialize', ['articles']);

Note: It is important that your serialize option is an array, e.g. ['articles'], so that your pagination information can be set under its own pagination key., <sub>(*9)</sub>

Your JsonView and XmlView responses will now contain the pagination information, and will look something like this:, <sub>(*10)</sub>

``` json { "articles": ["...", "...", "..."], "pagination": { "finder": "all", "page": 1, "current": 20, "count": 5000, "perPage": 20, "prevPage": false, "nextPage": true, "pageCount": 250, "sort": null, "direction": false, "limit": null, "sortDefault": false, "directionDefault": false } }, <sub>(*11)</sub>

### Configuring the Pagination Output

ApiPagination has four keys for configuration: `key`, `aliases`, `visible` and `model`.

* `key` allows you to change the name of the pagination key.

* `aliases` allows you to change names of the pagination detail keys.

* `visible` allows you to set which pagination keys will be exposed in the
  response. **Note:** Whenever setting a key's visibility, make sure to use the
  aliased name if you've given it one.

* `model` allows you to set the name of the model the pagination is applied on
  if the controller does not follow CakePHP conventions, e.g. `ArticlesIndexController`.
  Per default the model is the name of the controller, e.g. `Articles` for `ArticlesController`.

An example using all these configuration keys:

``` php
$this->loadComponent('BryanCrowe/ApiPagination.ApiPagination', [
    'key' => 'paging',
    'aliases' => [
        'page' => 'currentPage',
        'current' => 'resultCount'
    ],
    'visible' => [
        'currentPage',
        'resultCount',
        'prevPage',
        'nextPage'
    ],
    'model' => 'Articles',
]);

This configuration would yield:, <sub>(*12)</sub>

``` json { "articles": ["...", "...", "..."], "paging": { "prevPage": false, "nextPage": true, "currentPage": 1, "resultCount": 20 } }, <sub>(*13)</sub>

## Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed
recently.

## Testing

``` bash
$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details., <sub>(*14)</sub>

Security

If you discover any security related issues, please email bryan@bryan-crowe.com instead of using the issue tracker., <sub>(*15)</sub>

Credits

• Bryan Crowe
• All Contributors

License

The MIT License (MIT). Please see License File for more information., <sub>(*16)</sub>