Pagination

Webisters Pagination Library.

Installation
Getting Started
Rendering Views
Custom Language
URL
JSON-Encoding
Conclusion

Installation

The installation of this library can be done with Composer:

composer require Webisters/pagination

Getting Started

With the Pagination Library it is possible to work with objects of the Pager class.

And a Pager can be instantiated as in the example below:

use Framework\Pagination\Pager;
$currentPage = 3;
$itemsPerPage = 10;
$totalItems = 230;
$pager = new Pager($currentPage, $itemsPerPage, $totalItems);

Rendering Views

You can work with various Pager methods, but the ultimate goal is usually to render views to be displayed on the page.

The following features are available for rendering views: Pagination, HTML Head Links, HTTP Header Link, Front-end Frameworks Support, Default Rendering View, Custom Views.

Pagination

The default view name is pagination and it can be rendered as follows:

echo $pager->render();

An HTML code similar to this will be displayed:

<ul class="pagination">
    <li>
        <a rel="prev" href="https://domain.tld/blog/posts?page=2" title="Previous">&laquo;</a>
    </li>
    <li>
        <a href="https://domain.tld/blog/posts?page=1">1</a>
    </li>
    <li>
        <a href="https://domain.tld/blog/posts?page=2">2</a>
    </li>
    <li>
        <a rel="canonical" href="https://domain.tld/blog/posts?page=3" class="active">3</a>
    </li>
    <li>
        <a href="https://domain.tld/blog/posts?page=4">4</a>
    </li>
    <li>
        <a href="https://domain.tld/blog/posts?page=5">5</a>
    </li>
    <li>
        <a rel="next" href="https://domain.tld/blog/posts?page=4" title="Next">&raquo;</a>
    </li>
    <li>
        <a href="https://domain.tld/blog/posts?page=23">Last</a>
    </li>
</ul>

In addition to "full" rendering, it is also possible to render "short views":

echo $pager->renderShort();

See HTML below. It only has the previous and next links:

<ul class="pagination">
    <li>
        <a rel="prev" href="https://domain.tld/blog/posts?page=2" title="Previous">
            &laquo; Previous
        </a>
    </li>
    <li>
        <a rel="next" href="https://domain.tld/blog/posts?page=4" title="Next">
            Next &raquo;
        </a>
    </li>
</ul>

HTML Head Links

One way to optimize the indexing of pages visited by web crawlers and also SEO ranks is to print the pagination links in the head tag of the HTML page:

<head>
<title>Webisters Pagination</title>
<?= $pager->render('head') ?>
</head>

Example of rendering links with head view:

<head>
<title>Webisters Pagination</title>
<link rel="prev" href="https://domain.tld/blog/posts?page=2">
<link rel="canonical" href="https://domain.tld/blog/posts?page=3">
<link rel="next" href="https://domain.tld/blog/posts?page=4">
</head>

HTTP Header Link

When working with APIs it may be necessary to paginate the results and for this there is the HTTP Link Header.

With the Pager defined, it is possible to render the header view:

header('Link: ' . $pager->render('header'));

The Link sent header field will look like this:

Link: <https://domain.tld/blog/posts?page=1>; rel="first",<https://domain.tld/blog/posts?page=2>; rel="prev",<https://domain.tld/blog/posts?page=4>; rel="next",<https://domain.tld/blog/posts?page=23>; rel="last"

Front-end Frameworks Support

The Webisters Pagination Library works with the following front-end frameworks:

Note that it is necessary to load links from CSS files.

See an example using Bootstrap:

Insert the link tag with the CSS file.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css">

Render pagination using the bootstrap view:

echo $pager->render('bootstrap');

The result will be like the image below:

It is also possible to render the "short view". Note the view name suffixed with -short:

echo $pager->render('bootstrap-short');

And the result:

Webisters Pagination - Bootstrap Short View

Default Rendering View

You can always render views by passing their name in the render method.

The most common is that an application works with only one pagination style and for that it is possible to set the default view.

Once this is done, the Pager's render method can be called with no arguments and the default view will be rendered.

See an example setting the bulma view to default:

$pager->setDefaultView('bulma'); // static

And the call to render:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/css/bulma.min.css">
<?= $pager->render() ?>

And the result in the web browser:

The default view will also be used by the renderShort method

echo $pager->renderShort();

which will render the "short view":

Custom Views

If you need to use a different view style, add the view name and filepath:

$name = 'my-pager';
$filepath = __DIR__ . '/Views/my-pager.php';
$pager->setView($name, $filepath); // static

And then you can render it:

echo $pager->render('my-pager');

Note that it is possible to set the default view and call the render method with no arguments.

Custom Language

The default language used is English.

To set a different language, do this in the Pager constructor:

$language = new Framework\Language\Language('es');
$pager = new Pager($currentPage, $itemsPerPage, $totalItems, $language);

Or when needed via the setLanguage method:

$pager->setLanguage($language); // static

After setting the language, it is possible to render the pagination.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/semantic.min.css">
<?= $pager->render('semantic-ui') ?>

Example using Semantic UI with Spanish language:

If the Pagination Library is not localized in your language, you can contribute by adding it with a Pull Request.

It is also possible to add custom languages at runtime. See the Language Library to know more.

URL

The URL used by the Pager is obtained through the HTTP request.

In some cases it is necessary to generate pagination for other resources or, also, when working from the command line.

Then the URL can be passed into the constructor:

$url = 'https://domain.tld/blog/posts';
$pager = new Pager($currentPage, $itemsPerPage, $totalItems, url: $url);

Or whenever you want via the setUrl method:

$pager->setUrl($url); // static

JSON-Encoding

Nowadays, it is very common to use JSON to work with interactions through AJAX or APIs.

An application can respond the pagination links via the HTTP Header Link. However, it is also an option to put the links next to the message content.

Having a Pager object instantiated, just put it in to be encoded:

$contents = [
    'data' => [],
    'links' => $pager,
];
echo json_encode($contents, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

And the result will be similar to this:

{
    "data": [],
    "links": {
        "self": "https://domain.tld/blog/posts?page=3",
        "first": "https://domain.tld/blog/posts?page=1",
        "prev": "https://domain.tld/blog/posts?page=2",
        "next": "https://domain.tld/blog/posts?page=4",
        "last": "https://domain.tld/blog/posts?page=23"
    }
}

Conclusion

Webisters Pagination Library is an easy-to-use tool for PHP developers, beginners and experienced.
It's perfect for building full-featured pagination in a very simple way.
The more you use it, the more you will learn.

Did you find something wrong?
Be sure to let us know about it with an issue.
Thank you!