README

该项目正在寻找维护者 - 详情请见此处。

Pagerfanta

该项目适用于PHP 7。如果您需要PHP < 7的支持，请使用版本1.1.0的发布版。

用法

<?php

use Pagerfanta\Adapter\ArrayAdapter;
use Pagerfanta\Pagerfanta;

$adapter = new ArrayAdapter($array);
$pagerfanta = new Pagerfanta($adapter);

$pagerfanta->setMaxPerPage($maxPerPage); // 10 by default
$maxPerPage = $pagerfanta->getMaxPerPage();

$pagerfanta->setCurrentPage($currentPage); // 1 by default
$currentPage = $pagerfanta->getCurrentPage();

$nbResults = $pagerfanta->getNbResults();
$currentPageResults = $pagerfanta->getCurrentPageResults();

其他一些可用的方法

$pagerfanta->getNbPages();
$pagerfanta->haveToPaginate(); // whether the number of results is higher than the max per page
$pagerfanta->hasPreviousPage();
$pagerfanta->getPreviousPage();
$pagerfanta->hasNextPage();
$pagerfanta->getNextPage();
$pagerfanta->getCurrentPageOffsetStart();
$pagerfanta->getCurrentPageOffsetEnd();

根据用户选择更改页面

如果您正在使用以下示例路由生成器函数，则用户选择的页面将通过 page GET（查询字符串）参数可用。

然后您需要调用 setCurrentPage 并传入该参数的值

if (isset($_GET["page"])) {
    $pagerfanta->setCurrentPage($_GET["page"]);
}

setMaxPerPage 和 setCurrentPage

->setMaxPerPage() 和 ->setCurrentPage() 方法实现了一种流畅的接口

<?php

$pagerfanta
    ->setMaxPerPage($maxPerPage)
    ->setCurrentPage($currentPage);

->setMaxPerPage() 方法如果每页最大值无效则抛出异常

• Pagerfanta\Exception\NotIntegerMaxPerPageException
• Pagerfanta\Exception\LessThan1MaxPerPageException

两者都扩展自 Pagerfanta\Exception\NotValidMaxPerPageException.

->setCurrentPage() 方法如果页面无效则抛出异常

• Pagerfanta\Exception\NotIntegerCurrentPageException
• Pagerfanta\Exception\LessThan1CurrentPageException
• Pagerfanta\Exception\OutOfRangeCurrentPageException

所有这些都扩展自 Pagerfanta\Exception\NotValidCurrentPageException.

->setCurrentPage() 根据每页最大值抛出越界异常，因此如果您打算修改每页最大值，应在设置当前页之前进行。

(如果您想在Symfony项目中使用Pagerfanta，请参阅https://github.com/whiteoctober/WhiteOctoberPagerfantaBundle.)

适配器

适配器的概念非常简单。适配器只返回结果数量以及一个偏移量和长度的切片。这样，您可以通过创建一个适配器，将Pagerfanta适配到任何类型的分页。

适配器必须实现Pagerfanta\Adapter\AdapterInterface接口，它有两个方法

<?php

/**
 * Returns the number of results.
 *
 * @return integer The number of results.
 */
function getNbResults();

/**
 * Returns an slice of the results.
 *
 * @param integer $offset The offset.
 * @param integer $length The length.
 *
 * @return array|\Iterator|\IteratorAggregate The slice.
 */
function getSlice($offset, $length);

Pagerfanta附带以下适配器

ArrayAdapter

用于分页数组。

<?php

use Pagerfanta\Adapter\ArrayAdapter;

$adapter = new ArrayAdapter($array);

MongoAdapter

用于分页Mongo游标。

<?php

use Pagerfanta\Adapter\MongoAdapter;

$cursor = $collection->find();
$adapter = new MongoAdapter($cursor);

MandangoAdapter

用于分页Mandango查询。

<?php

use Pagerfanta\Adapter\MandangoAdapter;

$query = $mandango->getRepository('Model\Article')->createQuery();
$adapter = new MandangoAdapter($query);

DoctrineDbalAdapter

用于分页DoctrineDbal查询构建器。

<?php

use Pagerfanta\Adapter\DoctrineDbalAdapter;
use Doctrine\DBAL\Query\QueryBuilder;

$queryBuilder = new QueryBuilder($conn);
$queryBuilder->select('p.*')->from('posts', 'p');

$countQueryBuilderModifier = function ($queryBuilder) {
    $queryBuilder->select('COUNT(DISTINCT p.id) AS total_results')
          ->setMaxResults(1);
};

$adapter = new DoctrineDbalAdapter($queryBuilder, $countQueryBuilderModifier);

DoctrineDbalSingleTableAdapter

用于简化单表DoctrineDbal查询构建器的分页。

此适配器仅用于分页单表查询构建器，不涉及连接。

<?php

use Pagerfanta\Adapter\DoctrineDbalSingleTableAdapter;
use Doctrine\DBAL\Query\QueryBuilder;

$queryBuilder = new QueryBuilder($conn);
$queryBuilder->select('p.*')->from('posts', 'p');

$countField = 'p.id';

$adapter = new DoctrineDbalSingleTableAdapter($queryBuilder, $countField);

DoctrineORMAdapter

用于分页DoctrineORM查询对象。

<?php

use Pagerfanta\Adapter\DoctrineORMAdapter;

$queryBuilder = $entityManager->createQueryBuilder()
    ->select('u')
    ->from('Model\Article', 'u');
$adapter = new DoctrineORMAdapter($queryBuilder);

DoctrineODMMongoDBAdapter

用于分页DoctrineODMMongoDB查询构建器。

<?php

use Pagerfanta\Adapter\DoctrineODMMongoDBAdapter;

$queryBuilder = $documentManager->createQueryBuilder('Model\Article');
$adapter = new DoctrineODMMongoDBAdapter($queryBuilder);

DoctrineODMPhpcrAdapter

用于分页Doctrine PHPCR-ODM查询构建器。

<?php

use Pagerfanta\Adapter\DoctrineODMPhpcrAdapter;

$queryBuilder = $documentManager->createQueryBuilder();
$queryBuilder->from('Model\Article');
$adapter = new DoctrineODMPhpcrAdapter($queryBuilder);

DoctrineCollectionAdapter

要分页一个 Doctrine\Common\Collection\Collections 接口，您可以使用 DoctrineCollectionAdapter。它代理到Collections接口上的 count() 和 slice() 方法进行分页。如果您正在使用Doctrine ORMs Extra Lazy关联功能，这很有意义。

<?php

use Pagerfanta\Adapter\DoctrineCollectionAdapter;

$user = $em->find("Pagerfanta\Tests\Adapter\DoctrineORM\User", 1);

$adapter = new DoctrineCollectionAdapter($user->getGroups());

DoctrineSelectableAdapter

为了分页处理Doctrine\Common\Collection\Selectable接口，可以使用DoctrineSelectableAdapter。它使用Selectable接口中的matching()方法进行分页。当使用Doctrine Criteria对象过滤PersistentCollection时，这特别有用。

<?php

use Pagerfanta\Adapter\DoctrineSelectableAdapter;
use Doctrine\Common\Collections\Criteria;

$user = $em->find("Pagerfanta\Tests\Adapter\DoctrineORM\User", 1);
$comments = $user->getComments();
$criteria = Criteria::create()->andWhere(Criteria::expr()->in('id', array(1,2,3));

$adapter = new DoctrineSelectableAdapter($comments, $criteria);

注意，您不应将此适配器与未设置为使用EXTRA_LAZY获取模式的PersistentCollection一起使用。

使用count()方法时要小心，目前Doctrine2需要检索所有记录以计算元素数量。

ElasticaAdapter

要分页Elastica Query查询

<?php

use Elastica\Index;
use Elastica\Query;
use Elastica\Query\Term;
use Pagerfanta\Adapter\ElasticaAdapter;

// Searchable can be any valid searchable Elastica object. For example a Type or Index
$searchable = new Index($elasticaClient, 'index_name');
// A Query can be any valid Elastica query (json, array, Query object)
$query = new Query::create(new Term(array(
    'name' => 'Fred'
));

$adapter = new ElasticaAdapter($searchable, $query);

当分页大量文档时要小心。默认情况下，偏移量+限制不能超过10000。您可以在构建ElasticaAdapter时设置$maxResults参数来减轻这个问题。更多信息请参阅： #213。

PropelAdapter

要分页propel 1查询

<?php

use Pagerfanta\Adapter\PropelAdapter;

$adapter = new PropelAdapter($query);

Propel2Adapter

要分页propel 2查询

<?php

use Pagerfanta\Adapter\Propel2Adapter;

$adapter = new Propel2Adapter($query);

SolariumAdapter

要分页solarium查询

<?php

use Pagerfanta\Adapter\SolariumAdapter;

$query = $solarium->createSelect();
$query->setQuery('search term');

$adapter = new SolariumAdapter($solarium, $query);

FixedAdapter

当您需要自定义分页解决方案且不想为一次性用例实现完整适配器时，最佳使用。

无论查询哪一页，它总是返回相同的数据

<?php

use Pagerfanta\Adapter\FixedAdapter;

$nbResults = 5;
$results = array(/* ... */);

$adapter = new FixedAdapter($nbResults, $results);

ConcatenationAdapter

将其他适配器实例的结果合并为一个适配器。它保持子适配器和它们的结果的顺序。

<?php

use Pagerfanta\Adapter\ConcatenationAdapter;

$superAdapter = new ConcatenationAdapter(array($adapter1, $adapter2 /* ... */));

视图

视图用于渲染pagerfantas，这样您就可以在多个项目中重用pagerfantas的HTML，共享它们并使用其他开发者的。

视图实现Pagerfanta\View\ViewInterface接口，该接口有两个方法

<?php

/**
 * Renders a pagerfanta.
 *
 * The route generator is any callable to generate the routes receiving the page number
 * as first and unique argument.
 *
 * @param PagerfantaInterface $pagerfanta     A pagerfanta.
 * @param mixed               $routeGenerator A callable to generate the routes.
 * @param array               $options        An array of options (optional).
 */
function render(PagerfantaInterface $pagerfanta, $routeGenerator, array $options = array());

/**
 * Returns the canonical name.
 *
 * @return string The canonical name.
 */
function getName();

RouteGenerator示例

<?php

$routeGenerator = function($page) {
    return '/path?page='.$page;
};

Pagerfanta附带五个视图：默认视图、三个用于Twitter Bootstrap、一个用于Semantic UI和一个特殊的可选视图。

DefaultView

这是默认视图。

<?php

use Pagerfanta\View\DefaultView;

$view = new DefaultView();
$options = array('proximity' => 3);
$html = $view->render($pagerfanta, $routeGenerator, $options);

选项（默认）

• proximity（3）
• prev_message（上一页）
• next_message（下一页）
• css_disabled_class（disabled）
• css_dots_class（dots）
• css_current_class（current）
• dots_text（...）
• container_template（%pages%）
• page_template（%text%）
• span_template（%text%）

CSS

.pagerfanta {
}

.pagerfanta a,
.pagerfanta span {
    display: inline-block;
    border: 1px solid blue;
    color: blue;
    margin-right: .2em;
    padding: .25em .35em;
}

.pagerfanta a {
    text-decoration: none;
}

.pagerfanta a:hover {
    background: #ccf;
}

.pagerfanta .dots {
    border-width: 0;
}

.pagerfanta .current {
    background: #ccf;
    font-weight: bold;
}

.pagerfanta .disabled {
    border-color: #ccf;
    color: #ccf;
}

COLORS:

.pagerfanta a,
.pagerfanta span {
    border-color: blue;
    color: blue;
}

.pagerfanta a:hover {
    background: #ccf;
}

.pagerfanta .current {
    background: #ccf;
}

.pagerfanta .disabled {
    border-color: #ccf;
    color: #cf;
}

TwitterBootstrapView, TwitterBootstrap3View和TwitterBootstrap4View

这些视图生成用于Twitter Bootstrap的分页器。

TwitterBootstrapView用于Bootstrap 2；TwitterBootstrap3View用于Bootstrap 3；TwitterBootstrap4View用于Bootstrap 4（alpha）。

<?php

use Pagerfanta\View\TwitterBootstrapView;

$view = new TwitterBootstrapView();
$options = array('proximity' => 3);
$html = $view->render($pagerfanta, $routeGenerator, $options);

选项（默认）

• proximity（3）
• prev_message（← 上一页）
• prev_disabled_href（）
• next_message（下一页 →）
• next_disabled_href（）
• dots_message（…）
• dots_href（）
• css_container_class（pagination）
• css_prev_class（prev）
• css_next_class（next）
• css_disabled_class（disabled）
• css_dots_class（disabled）
• css_active_class（active）

SemanticUiView

此视图为Semantic UI生成分页器。

<?php

use Pagerfanta\View\SemanticUiView;

$view = new SemanticUiView();
$options = array('proximity' => 3);
$html = $view->render($pagerfanta, $routeGenerator, $options);

选项（默认）

• proximity（3）
• prev_message（← 上一页）
• prev_disabled_href（）
• next_message（下一页 →）
• next_disabled_href（）
• dots_message（…）
• dots_href（）
• css_container_class（pagination）
• css_item_class（item）
• css_prev_class（prev）
• css_next_class（next）
• css_disabled_class（disabled）
• css_dots_class（disabled）
• css_active_class（active）

OptionableView

此视图用于在不同视图中重用选项。

<?php

use Pagerfanta\DefaultView;
use Pagerfanta\OptionableView;

$defaultView = new DefaultView();

// view and default options
$myView1 = new OptionableView($defaultView, array('proximity' => 3));

$myView2 = new OptionableView($defaultView, array('prev_message' => 'Anterior', 'next_message' => 'Siguiente'));

// using in a normal way
$pagerfantaHtml = $myView2->render($pagerfanta, $routeGenerator);

// overwriting default options
$pagerfantaHtml = $myView2->render($pagerfanta, $routeGenerator, array('next_message' => 'Siguiente!!'));

贡献

我们欢迎对此项目的贡献，包括拉取请求、问题（以及现有问题上的讨论）。

如果您想贡献代码但不确定从哪里开始，请从问题列表开始。如果您是第一次贡献代码，您可能需要查看GitHub关于项目分叉的指南。

所有贡献者（无论是贡献代码、参与问题讨论，还是以其他方式参与）都必须遵守我们的行为准则。

致谢

Pagerfanta受到Zend Paginator的启发。

还要感谢Pablo Díez（pablodip@gmail.com）为Pagerfanta最初版本的大部分工作。

许可证

Pagerfanta遵循MIT许可证。