bcrowe / cakephp-api-pagination
CakePHP 4 plugin that injects pagination information into API responses.
Installs: 49 928
Dependents: 1
Suggesters: 0
Security: 0
Stars: 40
Watchers: 5
Forks: 14
Open Issues: 0
Type:cakephp-plugin
Requires
- php: >=7.2
- cakephp/cakephp: ^4.2
Requires (Dev)
- cakephp/cakephp-codesniffer: ^4.7
- phpunit/phpunit: ^8.5.23
- scrutinizer/ocular: 1.7
README
This is a simple component for CakePHP 4.2+ which injects pagination information from CakePHP's Paginator into serialized JsonView and XmlView responses.
See 1.x
and 2.x
releases and branches of this plugin for support of previous versions of CakePHP before 4.2
.
Install
Via Composer
$ composer require bcrowe/cakephp-api-pagination
Load the plugin by adding $this->addPlugin('BryanCrowe/ApiPagination');
to the bootsrap
method in your project’s src/Application.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.
Then, load ApiPaginationComponent
:
$this->loadComponent('BryanCrowe/ApiPagination.ApiPagination');
Then, go ahead and set your paginated view variable like so:
$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.
Your JsonView and XmlView responses will now contain the pagination information, and will look something like this:
{ "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 } }
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
forArticlesController
.
An example using all these configuration keys:
$this->loadComponent('BryanCrowe/ApiPagination.ApiPagination', [ 'key' => 'paging', 'aliases' => [ 'page' => 'currentPage', 'current' => 'resultCount' ], 'visible' => [ 'currentPage', 'resultCount', 'prevPage', 'nextPage' ], 'model' => 'Articles', ]);
This configuration would yield:
{ "articles": ["...", "...", "..."], "paging": { "prevPage": false, "nextPage": true, "currentPage": 1, "resultCount": 20 } }
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING and CONDUCT for details.
Security
If you discover any security related issues, please email bryan@bryan-crowe.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.