This tutorial will cover installation and usage examples.
composer require "knplabs/knp-components:~1.2"
As mentioned in introduction paginator uses event listeners to paginate the given data. First we will start from the simplest data - array. Lets add some code in index.php and see it in action:
<?php
// file: index.php
include 'autoloader.php';
// usage examples will continue here
use Knp\Component\Pager\Paginator; // used class name
// end of line and tab definition
define('EOL', php_sapi_name() === 'cli' ? PHP_EOL : '<br/>');
define('TAB', php_sapi_name() === 'cli' ? "\t" : '<span style="margin-left:25px"/>');
$paginator = new Paginator; // initializes default event dispatcher, with standard listeners
$target = range('a', 'z'); // an array to paginate
// paginate target and generate representation class, it can be overrided by event listener
$pagination = $paginator->paginate($target, 1/*page number*/, 10/*limit per page*/);
echo 'total count: '.$pagination->getTotalItemCount().EOL;
echo 'pagination items of page: '.$pagination->getCurrentPageNumber().EOL;
// iterate items
foreach ($pagination as $item) {
//...
echo TAB.'paginated item: '.$item.EOL;
}
$pagination = $paginator->paginate($target, 3/*page number*/, 10/*limit per page*/);
echo 'pagination items of page: '.$pagination->getCurrentPageNumber().EOL;
// iterate items
foreach ($pagination as $item) {
//...
echo TAB.'paginated item: '.$item.EOL;
}
$paginator->paginate($target...) will return pagination class, which is by default SlidingPagination it executes a $pagination->renderer callback with all arguments reguired in view template. Its your decision to implement it whatever way you like.
Note: this is the default method. There will be more examples on how to render pagination templates
So if you by default print the pagination you should see something like:
<?php
// continuing in file: index.php
// ...
echo $pagination; // outputs: "override in order to render a template"
Now if we override the renderer callback
<?php
// continuing in file: index.php
// ...
$pagination->renderer = function($data) {
return EOL.TAB.'page range: '.implode(' ', $data['pagesInRange']).EOL;
};
echo $pagination; // outputs: "page range: 1 2 3"
It is not uncommonly that the result of a database query should be sorted by multiple columns. For example users should be sorted by lastname and by firstname:
$query = $entityManager->createQuery('SELECT u FROM User');
$pagination = $paginator->paginate($query, 1/*page number*/, 20/*limit per page*/, array(
'defaultSortFieldName' => array('u.lastname', 'u.firstname'),
'defaultSortDirection' => 'asc',
));
The Paginator will add an ORDER BY
automatically for each attribute for the
defaultSortFieldName
option.
You can also filter the result of a database query by multiple columns. For example users should be filtered by lastname or by firstname:
$query = $entityManager->createQuery('SELECT u FROM User');
$pagination = $paginator->paginate($query, 1/*page number*/, 20/*limit per page*/, array(
'defaultFilterFields' => array('u.lastname', 'u.firstname'),
));
If the filterValue
parameter is set, the Paginator will add an WHERE
condition automatically
for each attribute for the defaultFilterFields
option. The conditions are OR
-linked.