Pagination¶

The Bundle Chill\MainBundle provides a Pagination api which allow you to easily divide results list on different pages.

A simple example¶

In the controller, get the Chill\Main\Pagination\PaginatorFactory from the Container and use this PaginatorFactory to create a Paginator instance.

<?php

declare(strict_types=1);

/*
 * Chill is a software for social workers
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

namespace Chill\MyBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class example extends Controller
{
    public function yourAction()
    {
        $em = $this->getDoctrine()->getManager();
        // first, get the number of total item are available
        $total = $em
            ->createQuery('SELECT COUNT (item.id) FROM ChillMyBundle:Item item')
            ->getSingleScalarResult();

        // get the PaginatorFactory
        $paginatorFactory = $this->get('chill_main.paginator_factory');

        // create a pagination instance. This instance is only valid for
        // the current route and parameters
        $paginator = $paginatorFactory->create($total);

        // launch your query on item. Limit the query to the results
        // for the current page using the paginator
        $items = $em->createQuery('SELECT item FROM ChillMyBundle:Item item WHERE <your clause>')
            // use the paginator to get the first item number
            ->setFirstResult($paginator->getCurrentPage()->getFirstItemNumber())
            // use the paginator to get the number of items to display
            ->setMaxResults($paginator->getItemsPerPage());

        return $this->render(
            'ChillMyBundle:Item:list.html.twig',
            [
                'items' => $items,
                'paginator' => $paginator,
            ]
        );
    }
}

Then, render the pagination using the dedicated twig function.

{% extends "@ChillPerson/Person/layout.html.twig"  %}

{% block title 'Item list'|trans %}

{% block content %}

<table>

{# ... your items here... #}

</table>

{% if items|length < paginator.getTotalItems %}
{{ chill_pagination(paginator) }}
{% endif %}

The function chill_pagination will, by default, render a link to the 10 previous page (if they exists) and the 10 next pages (if they exists). Assuming that we are on page 5, the function will render a list to

Previous 1 2 3 4 **5** 6 7 8 9 10 11 12 13 14 Next

Understanding the magic¶

Where does the `$paginator` get the page number ?¶

Internally, the $paginator object has a link to the Request object, and it reads the page parameter which contains the current page number. If this parameter is not present, the $paginator assumes that we are on page 1.

The $paginator get the current page from the request.

Where does the `$paginator` get the number of items per page ?¶

As above, the $paginator can get the number of items per page from the Request. If none is provided, this is given by the configuration which is, by default, 50 items per page.

`PaginatorFactory`, `Paginator` and `Page`¶

`PaginatorFactory`¶

The PaginatorFactory may create more than one Paginator in a single action. Those Paginator instance may redirect to different routes and/or routes parameters.

// create a paginator for the route 'my_route' with some parameters (arg1 and arg2)
$paginatorMyRoute = $paginatorFactory->create($total, 'my_route', array('arg1' => 'foo', 'arg2' => $bar);

Those parameters will override the current parameters.

The PaginatorFactory has also some useful shortcuts :

// get current page number
$paginatorFactory->getCurrentPageNumber( )
// get the number of items per page **for the current request**
$paginatorFactory->getCurrentItemsPerPage( )
// get the number of the first item **for the current page**
$paginatorFactory->getCurrentPageFirstItemNumber( )

Working with `Paginator` and `Page`¶

The paginator has some function to give the number of pages are required to displayed all the results, and give some information about the number of items per page :

// how many page count this paginator ?
$paginator->countPages(); // return 20 in our example

// we may get the number of items per page
$paginator->getItemsPerPage(); // return 20 in our example

A Paginator instance create instance of Page, each Page, which is responsible for generating the URL to the page number it represents. Here are some possibilities using Page and Paginator :

// get the current page
$page = $paginator->getCurrentPage();
// on which page are we ?
$page->getNumber(); // return 5 in this example (we are on page 5)
// generate the url for page 5
$page->generateUrl(); // return '/<your route here>?page=5
// what is the first item number on this page ?
$page->getFistItemNumber(); // return 101 in our example (20 items per page)
// what is the last item number on this page ?
$page->getLastItemNumber(); // return 120 in our example

// we can access directly the next and current page
if ($paginator->hasNextPage()) {
    $next = $paginator->getNextPage();
}
if ($paginator->hasPreviousPage()) {
    $previous = $paginator->getPreviousPage();
}

// we can access directly to a given page number
if ($paginator->hasPage(10)) {
   $page10 = $paginator->getPage(10);
}

// we can iterate over our pages through a generator
foreach ($paginator->getPagesGenerator() as $page) {
   $page->getNumber();
}

// check that a page object is the current page
$paginator->isCurrentPage($page); // return false

Warning

When calling a page which does not exists, the Paginator will throw a RuntimeException. Example :

// our last page is 10
$paginator->getPage(99); // out of range => throw `RuntimeException`

// our current page is 1 (the first page)
$paginator->getPreviousPage; // does not exists (the fist page is always 1) => throw `RuntimeException`

Note

When you create a Paginator for the current route and route parameters, the Page instances will keep the same parameters and routes :

// assuming our route is 'my_route', for the pattern '/my/{foo}/route',
// and the current route is '/my/value/route?arg2=bar'

// create a paginator for the current route and route parameters :
$paginator = $paginatorFactory->create($total);

// get the next page
if ($paginator->hasNext()) {
   $next = $paginator->getNextPage();

   // get the route to the page
   $page->generateUrl(); // will print 'my/value/route?arg2=bar&page=2'
}

Having a look to the full classes documentation may provide some useful information.

Customizing the rendering of twig’s `chill_pagination`¶

You can provide your own layout for rendering the pagination: provides your twig template as a second argument :

{{ chill_pagination(paginator, 'MyBundle:Pagination:MyTemplate.html.twig') }}

The template will receive the $paginator as paginator variable. Let’s have a look at the current template.

Pagination¶

A simple example¶

Understanding the magic¶

Where does the $paginator get the page number ?¶

Where does the $paginator get the number of items per page ?¶

PaginatorFactory, Paginator and Page¶

PaginatorFactory¶

Working with Paginator and Page¶

Customizing the rendering of twig’s chill_pagination¶