Overview

Source Codacy Badge

This package is for creating simple pagination links based on the current page number, and the total number of records.

The pagination output will look something like this:

Example pagination

Installation

Install via composer

1
composer require vespula/paginator

Usage

Using the paginator is easy. All you need is a current page number, the total number of records, and a PSR-7 URI object such as Zend's Diactoros. Several frameworks, such as Slim, already include a PSR-7 Uri object as part of the Request object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?php
use Vespula\Paginator\Paginator;
use Vespula\Paginator\Decorator\Generic;
use Zend\Diactoros\Uri;

$decorator = new Generic();
$paginator = new Paginator($decorator);
$uri = new Uri('http://example.com');

$page = 2;
$total = 234;

echo $paginator->paginate($page, $total, $uri); 

And the result:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<ul class="pagination">
    <li><a href="http://example.com?page=1">First</a></li>
    <li><a href="http://example.com?page=1">Previous</a></li>
    <li><a href="http://example.com?page=1">1</a></li>
    <li class="active"><a href="http://example.com?page=2">2</a></li>
    <li><a href="http://example.com?page=3">3</a></li>
    <li><a href="http://example.com?page=4">4</a></li>
    <li><a href="http://example.com?page=5">5</a></li>
    <li><a href="http://example.com?page=6">6</a></li>
    <li><a href="http://example.com?page=7">7</a></li>
    <li><a href="http://example.com?page=8">8</a></li>
    <li><a href="http://example.com?page=9">9</a></li>
    <li><a href="http://example.com?page=10">10</a></li>
    <li><a href="http://example.com?page=3">Next</a></li>
    <li><a href="http://example.com?page=24">Last</a></li>
</ul>

Note

With the generic decorator, it is up to you to create the CSS for display. See the page on the generic decorator for some sample CSS.

Changing the paging (rows per page)

You can easily modify the paging from the default of 10 to any number. This should match any paging you are using in your DB queries or ORM.

1
2
3
4
5
6
7
8
<?php
$paginator = new Paginator($decorator);
$uri = new Uri('http://example.com');

$page = 2;
$total = 234;

echo $paginator->setPaging(25)->paginate($page, $total, $uri); 

Changing the query parameter

The default query parameter is 'page'. You can change that by using the 4th parameter on the paginate() method.

1
2
3
<?php
$param = 'p';
echo $paginator->setPaging(25)->paginate($page, $total, $uri, $param);

The resulting href will look like this <a href="http://example.com?p=1">1</a>

Getting metadata about the pagination

You can get an array of metadata about the pagingation by calling getMeta() AFTER you have called the paginate() method. The getMeta() method needs to know the current page and the total pages, so it must come after paginate().

With this metadata, you can do things like "Showing 1 to 10 of 432"

1
2
3
4
<?php
$html = $paginator->paginate($page, $total, $uri);

$meta = $paginator->getMeta();

$meta might look like this, depending on your arguments.

1
2
3
4
5
6
7
8
9
Array
(
    [page] => 2
    [total] => 234
    [pages] => 24
    [paging] => 10
    [start] => 11
    [end] => 20
)

Getting and setting the decorator

At anytime after constructing the paginator, you can get the decorator by calling $decorator = $paginator->getDecorator(). This allows you to modify decorator config options prior to outputting the html.

If you need to set a new decorator after construction, you can call the $paginator->setDecorator($decorator) method.