A lightweight PHP paginator, for generating pagination controls in the style of Stack Overflow and Flickr.

Jason Grimes

Last update: Dec 21, 2022

Related tags

Laravel php-paginator

Overview

PHP Paginator

A lightweight PHP paginator, for generating pagination controls in the style of Stack Overflow and Flickr. The "first" and "last" page links are shown inline as page numbers, and excess page numbers are replaced by ellipses.

Screenshots

These examples show how the paginator handles overflow when there are a lot of pages. They're rendered using the sample templates provided in the examples directory, which depend on Twitter Bootstrap. You can easily use your own custom HTML to render the pagination control instead.

Default template:

Small template (useful for mobile interfaces):

The small template renders the page number as a select list to save space:

Installation

Install with composer:

composer require "jasongrimes/paginator:~1.0"

Basic usage

Here's a quick example using the defaults:

<?php

require '../vendor/autoload.php';

use JasonGrimes\Paginator;

$totalItems = 1000;
$itemsPerPage = 50;
$currentPage = 8;
$urlPattern = '/foo/page/(:num)';

$paginator = new Paginator($totalItems, $itemsPerPage, $currentPage, $urlPattern);

?>
<html>
  <head>
    <!-- The default, built-in template supports the Twitter Bootstrap pagination styles. -->
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
  </head>
  <body>

    <?php 
      // Example of rendering the pagination control with the built-in template.
      // See below for information about using other templates or custom rendering.

      echo $paginator; 
    ?>
    
  </body>
</html>

This will output the following:

<ul class="pagination">
  <li><a href="/foo/page/7">&laquo; Previous</a></li>
  <li><a href="/foo/page/1">1</a></li>
  <li class="disabled"><span>...</span></li>
  <li><a href="/foo/page/5">5</a></li>
  <li><a href="/foo/page/6">6</a></li>
  <li><a href="/foo/page/7">7</a></li>
  <li class="active"><a href="/foo/page/8">8</a></li>
  <li><a href="/foo/page/9">9</a></li>
  <li><a href="/foo/page/10">10</a></li>
  <li><a href="/foo/page/11">11</a></li>
  <li><a href="/foo/page/12">12</a></li>
  <li class="disabled"><span>...</span></li>
  <li><a href="/foo/page/20">20</a></li>
  <li><a href="/foo/page/9">Next &raquo;</a></li>
</ul>

To render it with one of the other example templates, just make sure the variable is named $paginator and then include the template file:

$paginator = new Paginator($totalItems, $itemsPerPage, $currentPage, $urlPattern);

include '../vendor/jasongrimes/paginator/examples/pagerSmall.phtml';

If the example templates don't suit you, you can iterate over the paginated data to render your own pagination control.

Rendering a custom pagination control

Use $paginator->getPages(), $paginator->getNextUrl(), and $paginator->getPrevUrl() to render a pagination control with your own HTML. For example:

<ul class="pagination">
    <?php if ($paginator->getPrevUrl()): ?>
        <li><a href="<?php echo $paginator->getPrevUrl(); ?>">&laquo; Previous</a></li>
    <?php endif; ?>

    <?php foreach ($paginator->getPages() as $page): ?>
        <?php if ($page['url']): ?>
            <li <?php echo $page['isCurrent'] ? 'class="active"' : ''; ?>>
                <a href="<?php echo $page['url']; ?>"><?php echo $page['num']; ?></a>
            </li>
        <?php else: ?>
            <li class="disabled"><span><?php echo $page['num']; ?></span></li>
        <?php endif; ?>
    <?php endforeach; ?>

    <?php if ($paginator->getNextUrl()): ?>
        <li><a href="<?php echo $paginator->getNextUrl(); ?>">Next &raquo;</a></li>
    <?php endif; ?>
</ul>

<p>
    <?php echo $paginator->getTotalItems(); ?> found.
    
    Showing 
    <?php echo $paginator->getCurrentPageFirstItem(); ?> 
    - 
    <?php echo $paginator->getCurrentPageLastItem(); ?>.
</p>

See the examples directory for more sample templates.

Pages data structure

$paginator->getPages();

getPages() returns a data structure like the following:

array ( 
    array ('num' => 1,     'url' => '/foo/page/1',  'isCurrent' => false),
    array ('num' => '...', 'url' => NULL,           'isCurrent' => false),
    array ('num' => 5,     'url' => '/foo/page/5',  'isCurrent' => false),
    array ('num' => 6,     'url' => '/foo/page/6',  'isCurrent' => false),
    array ('num' => 7,     'url' => '/foo/page/7',  'isCurrent' => false),
    array ('num' => 8,     'url' => '/foo/page/8',  'isCurrent' => true),
    array ('num' => 9,     'url' => '/foo/page/9',  'isCurrent' => false),
    array ('num' => 10,    'url' => '/foo/page/10', 'isCurrent' => false),
    array ('num' => 11,    'url' => '/foo/page/11', 'isCurrent' => false),
    array ('num' => 12,    'url' => '/foo/page/12', 'isCurrent' => false),
    array ('num' => '...', 'url' => NULL,           'isCurrent' => false),
    array ('num' => 20,    'url' => '/foo/page/20', 'isCurrent' => false),
)

Customizing the number of pages shown

By default, no more than 10 pages are shown, including the first and last page, with the overflow replaced by ellipses. To change the default number of pages:

$paginator->setMaxPagesToShow(5);

Comments

Created interface to make editing HTML structure easier.

This update allows the developer to alter the sections of HTML on a per-pagination basis, or leave it as the default. Manually accessing the pagination system is okay, but things can be missed and cause discrepancies.

You can edit the strings via the setString method and will automatically parse the strings for you. The README has been udpated to provide more info.

opened by verenion 2
Configurable Next and Previous text

At the moment, the $previousText and $nextText variables are hard coded in the library. I think it would be a useful feature to have these configurable, for example for supporting translation. Would you consider adding this to the library?

Regards,

opened by gdejong 1
Custom next and previous text button

For greater customization and flexibility, I created two attributes (previousText and nextText) representing the text for the buttons: next and previous.

opened by dersonsena 1
[WCAG compliance] Include ARIA controls in the paginator
Include ARIA controls in the paginator. Improve assistive technology interactions.

Labeling the navigation links.

Indicate which element is currently active.
opened by wasabeto 0

Suppress link for current page in full width display

In the full width display, the current page button needs to have it's link suppressed.

/src/JasonGrimes/Paginator.php Line 289 needs to be changed from

                $html .= '<li' . ($page['isCurrent'] ? ' class="active"' : '') . '><a href="' . htmlspecialchars($page['url']) . '">' . htmlspecialchars($page['num']) . '</a></li>';

to:

                $html .= '<li' . ($page['isCurrent'] ? ' class="active"><a href="#' : '><a href="' . htmlspecialchars($page['url'])) . '">' . htmlspecialchars($page['num']) . '</a></li>';

opened by apmuthu 0

Add support for delegation of url generation

This pull request will allow Paginator to delegate URL generation. This can be useful when integrating with frameworks that have have a routing service such as Symfony. If a UrlGeneratorInteface object is not set Paginator defaults to using the url pattern

opened by seydu 0
Added basic stylesheet example

Hi Jason, love this library, exactly what I needed. I'm not using a CSS framework so I ended up figuring out some quick and dirty SCSS to style. I added it to the README in its own new little section.

opened by pnoeric 0

Releases(1.0.3)

1.0.3(Jul 11, 2018)

Source code(tar.gz)
Source code(zip)
1.0.2(Oct 15, 2015)

Configurable labels for next and previous buttons in the default template.
Source code(tar.gz)
Source code(zip)
1.0.1(Oct 13, 2014)

Source code(tar.gz)
Source code(zip)

A lightweight PHP paginator, for generating pagination controls in the style of Stack Overflow and Flickr.

Related tags

Overview

PHP Paginator

Screenshots

Installation

Basic usage

Rendering a custom pagination control

Pages data structure

Customizing the number of pages shown

Comments

Created interface to make editing HTML structure easier.

Configurable Next and Previous text

Custom next and previous text button

[WCAG compliance] Include ARIA controls in the paginator

Suppress link for current page in full width display

Add support for delegation of url generation

Added basic stylesheet example

Releases(1.0.3)

1.0.3(Jul 11, 2018)

1.0.2(Oct 15, 2015)

1.0.1(Oct 13, 2014)

Owner

Jason Grimes

A base API controller for Laravel that gives sorting, filtering, eager loading and pagination for your resources

In-place pagination without page refresh by using Backbone.js with Laravel PHP framework

Bring Laravel 8's cursor pagination to Laravel 6, 7

Cursor pagination for your Laravel API

Laravel 7 Ajax Pagination Example

A simple Laravel package for generating download links with options such as expire time, IP restrictions, etc.

Avatar Generating Package for Laravel.

Library for generating random names (for table-top roleplaying games)

Run patches migration style in your Laravel applications.

Laravel style jquery validation plugin

Let's base your Laravel project with PROS style

Livewire UI components with tailwind base style

Viewi for Laravel: Build full-stack and completely reactive user interfaces with PHP.

Laravel Livewire (TALL-stack) form generator with realtime validation, file uploads, array fields, blade form input components and more.

Gallium is a TALL stack starter kit offering a robust set of options enabling you to get up and running in a snap.

Jumpstart your web development journey with the HALT Stack Starter Kit, a one-command solution for creating dynamic, scalable, and clean web applications.

A full-stack framework for Laravel that takes the pain out of building dynamic UIs.

Livewire Notifier is a simple notifications system with zero dependencies above TALL-stack

Laravel Package to generate CRUD Files using TALL Stack