Pagination

CodeIgniter provides a very simple, but flexible pagination library that is simple to theme, works with the model,and capable of supporting multiple paginators on a single page.

Loading the Library

Like all services in CodeIgniter, it can be loaded via Config\Services, though you usually will not needto load it manually:

  1. $pager = \Config\Services::pager();

Paginating Database Results

In most cases, you will be using the Pager library in order to paginate results that you retrieve from the database.When using the Model class, you can use its built-in paginate() method to automaticallyretrieve the current batch of results, as well as set up the Pager library so it’s ready to use in your controllers.It even reads the current page it should display from the current URL via a page=X query variable.

To provide a paginated list of users in your application, your controller’s method would look something like:

  1. <?php namespace App\Controllers;
  2.  
  3. use CodeIgniter\Controller;
  4.  
  5. class UserController extends Controller
  6. {
  7.     public function index()
  8.     {
  9.         $model = new \App\Models\UserModel();
  10.  
  11.         $data = [
  12.             'users' => $model->paginate(10),
  13.             'pager' => $model->pager
  14.         ];
  15.  
  16.         echo view('users/index', $data);
  17.     }
  18. }

In this example, we first create a new instance of our UserModel. Then we populate the data to send to the view.The first element is the results from the database, users, which is retrieved for the correct page, returning10 users per page. The second item that must be sent to the view is the Pager instance itself. As a convenience,the Model will hold on to the instance it used and store it in the public class variable, $pager. So, we grabthat and assign it to the $pager variable in the view.

Within the view, we then need to tell it where to display the resulting links:

  1. <?= $pager->links() ?>

And that’s all it takes. The Pager class will render First and Last page links, as well as Next and Previous linksfor any pages more than two pages on either side of the current page.

If you prefer a simpler output, you can use the simpleLinks() method, which only uses “Older” and “Newer” links,instead of the details pagination links:

  1. <?= $pager->simpleLinks() ?>

Behind the scenes, the library loads a view file that determines how the links are formatted, making it simple tomodify to your needs. See below for details on how to completely customize the output.

Paginating Multiple Results

If you need to provide links from two different result sets, you can pass group names to most of the paginationmethods to keep the data separate:

  1. // In the Controller
  2. public function index()
  3. {
  4.     $userModel = new \App\Models\UserModel();
  5.     $pageModel = new \App\Models\PageModel();
  6.  
  7.     $data = [
  8.         'users' => $userModel->paginate(10, 'group1'),
  9.         'pages' => $pageModel->paginate(15, 'group2'),
  10.         'pager' => $userModel->pager
  11.     ];
  12.  
  13.     echo view('users/index', $data);
  14. }
  15.  
  16. // In the views:
  17. <?= $pager->links('group1') ?>
  18. <?= $pager->simpleLinks('group2') ?>

Manual Pagination

You may find times where you just need to create pagination based on known data. You can create links manuallywith the makeLinks() method, which takes the current page, the number of results per page, andthe total number of items as the first, second, and third parameters, respectively:

  1. <?= $pager->makeLinks($page, $perPage, $total) ?>

This will, by default, display the links in the normal manner, as a series of links, but you can change the displaytemplate used by passing in the name of the template as the fourth parameter. More details can be found in the followingsections.

  1. <?= $pager->makeLinks($page, $perPage, $total, 'template_name') ?>

It is also possible to use a URI segment for the page number, instead of the page query parameter. Simply specify the segment number to use as the fifth parameter to makeLinks(). URIs generated by the pager would then look like https://domain.tld/model/[pageNumber] instead of https://domain.tld/model?page=[pageNumber].:

  1. <?= $pager->makeLinks($page, $perPage, $total, 'template_name', $segment) ?>

Please note: $segment value cannot be greater than the number of URI segments plus 1.

If you in need to show many pagers on one page then additional parameter which will define a group could be helpful:

  1. $pager = service('pager');
  2. $pager->setPath('path/for/my-group', 'my-group'); // Additionally you could define path for every group.
  3. $pager->makeLinks($page, $perPage, $total, 'template_name', $segment, 'my-group');

Paginating with Only Expected Queries

By default, all GET queries are shown in the pagination links.

For example, when accessing the URL http://domain.tld?search=foo&order=asc&hello=i+am+here&page=2, the page 3 link can be generated, along with the other links, as follows:

  1. echo $pager->links();
  2. // Page 3 link: http://domain.tld?search=foo&order=asc&hello=i+am+here&page=3

The only() method allows you to limit this just to queries already expected:

  1. echo $pager->only(['search', 'order'])->links();
  2. // Page 3 link: http://domain.tld?search=foo&order=asc&page=3

The page query is enabled by default. And only() acts in all pagination links.

View Configuration

When the links are rendered out to the page, they use a view file to describe the HTML. You can easily change the viewthat is used by editing app/Config/Pager.php:

  1. public $templates = [
  2.     'default_full'   => 'CodeIgniter\Pager\Views\default_full',
  3.     'default_simple' => 'CodeIgniter\Pager\Views\default_simple'
  4. ];

This setting stores the alias and namespaced view paths for the view thatshould be used. The default_full and default_simple views are used for the links() and simpleLinks()methods, respectively. To change the way those are displayed application-wide, you could assign a new view here.

For example, say you create a new view file that works with the Foundation CSS framework, andyou place that file at app/Views/Pagers/foundation_full.php. Since the application directory isnamespaced as App, and all directories underneath it map directly to segments of the namespace, you can locatethe view file through it’s namespace:

  1. 'default_full'   => 'App\Views\Pagers\foundation_full',

Since it is under the standard app/Views directory, though, you do not need to namespace it since theview() method can locate it by filename. In that case, you can simply give the sub-directory and file name:

  1. 'default_full'   => 'Pagers/foundation_full',

Once you have created the view and set it in the configuration, it will automatically be used. You don’t have toreplace the existing templates. You can create as many additional templates as you need in the configurationfile. A common situation would be needing different styles for the frontend and the backend of your application.

  1. public $templates = [
  2.     'default_full'   => 'CodeIgniter\Pager\Views\default_full',
  3.     'default_simple' => 'CodeIgniter\Pager\Views\default_simple',
  4.     'front_full'     => 'App\Views\Pagers\foundation_full',
  5. ];

Once configured, you can specify it as a the last parameter in the links(), simpleLinks(), and makeLinks()methods:

  1. <?= $pager->links('group1', 'front_full') ?>
  2. <?= $pager->simpleLinks('group2', 'front_full') ?>
  3. <?= $pager->makeLinks($page, $perPage, $total, 'front_full') ?>

Creating the View

When you create a new view, you only need to create the code that is needed for creating the pagination links themselves.You should not create unnecessary wrapping divs since it might be used in multiple places and you only limit theirusefulness. It is easiest to demonstrate creating a new view by showing you the existing default_full template:

  1. <?php $pager->setSurroundCount(2) ?>
  2.  
  3. <nav aria-label="Page navigation">
  4.     <ul class="pagination">
  5.     <?php if ($pager->hasPrevious()) : ?>
  6.         <li>
  7.             <a href="<?= $pager->getFirst() ?>" aria-label="First">
  8.                 <span aria-hidden="true">First</span>
  9.             </a>
  10.         </li>
  11.         <li>
  12.             <a href="<?= $pager->getPrevious() ?>" aria-label="Previous">
  13.                 <span aria-hidden="true">&laquo;</span>
  14.             </a>
  15.         </li>
  16.     <?php endif ?>
  17.  
  18.     <?php foreach ($pager->links() as $link) : ?>
  19.         <li <?= $link['active'] ? 'class="active"' : '' ?>>
  20.             <a href="<?= $link['uri'] ?>">
  21.                 <?= $link['title'] ?>
  22.             </a>
  23.         </li>
  24.     <?php endforeach ?>
  25.  
  26.     <?php if ($pager->hasNext()) : ?>
  27.         <li>
  28.             <a href="<?= $pager->getNext() ?>" aria-label="Previous">
  29.                 <span aria-hidden="true">&raquo;</span>
  30.             </a>
  31.         </li>
  32.         <li>
  33.             <a href="<?= $pager->getLast() ?>" aria-label="Last">
  34.                 <span aria-hidden="true">Last</span>
  35.             </a>
  36.         </li>
  37.     <?php endif ?>
  38.     </ul>
  39. </nav>

setSurroundCount()

In the first line, the setSurroundCount() method specifies than we want to show two links to either side ofthe current page link. The only parameter that it accepts is the number of links to show.

hasPrevious() & hasNext()

These methods return a boolean true if there are more links that can be displayed on either side of the current page,based on the value passed to setSurroundCount. For example, let’s say we have 20 pages of data. The currentpage is page 3. If the surrounding count is 2, then the following links would show up in the list: 1, 2, 3, 4, and 5.Since the first link displayed is page one, hasPrevious() would return false since there is no page zero. However,hasNext() would return true since there are 15 additional pages of results after page five.

getPrevious() & getNext()

These methods return the URL for the previous or next pages of results on either side of the numbered links. See theprevious paragraph for a full explanation.

getFirst() & getLast()

Much like getPrevious() and getNext(), these methods return links to the first and last pages in theresult set.

links()

Returns an array of data about all of the numbered links. Each link’s array contains the uri for the link, thetitle, which is just the number, and a boolean that tells whether the link is the current/active link or not:

  1. $link = [
  2.         'active' => false,
  3.         'uri'    => 'http://example.com/foo?page=2',
  4.         'title'  => 1
  5. ];