bcrowe / cakephp-api-pagination
CakePHP 4 plugin that injects pagination information into API responses.
Installs: 44 428
Dependents: 1
Suggesters: 0
Security: 0
Stars: 40
Watchers: 5
Forks: 11
Open Issues: 0
Type:cakephp-plugin
Requires
- php: >=7.2
- cakephp/cakephp: ^4.0
Requires (Dev)
- cakephp/cakephp-codesniffer: ~4.0.0
- phpunit/phpunit: ^8.5
- scrutinizer/ocular: 1.7
README
This is a simple component for CakePHP 4 which injects pagination information from CakePHP's Paginator into serialized JsonView and XmlView responses.
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.