包简介

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.

README 文档

README

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);

jasongrimes/paginator 适用场景与选型建议

jasongrimes/paginator 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 1.31M 次下载、GitHub Stars 达 374，最近一次更新时间为 2014 年 09 月 28 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「pager」「paginator」「pagination」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 jasongrimes/paginator 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 jasongrimes/paginator 我们能提供哪些服务？

定制开发 / 二次开发

基于 jasongrimes/paginator 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发