分页（Pagination）¶

当需要呈现大量数据时我们需要用到该分页组件。Phalcon\Paginator 提供了便捷数据集访问接口。

数据适配器（Data Adapters）¶

This component makes use of adapters to encapsulate different sources of data:

Adapter	Description
NativeArray	使用数组当数据源。
Model	使用模型结果集 Phalcon\Mvc\Model\Resultset <../api/Phalcon_Mvc_Model_Resultset> 当数据源。因为 PDO 不支持游标，所以不适合大数据量的翻页。
QueryBuilder	Use a Phalcon\Mvc\Model\Query\Builder object as source data
sql	通过设置原生 SQL 获取数据源。

示例（Examples）¶

In the example below, the paginator will use the result of a query from a model as its source data, and limit the displayed data to 10 records per page:

<?PHP

use Phalcon\Paginator\Adapter\Model as PaginatorModel;

// Current page to show
// In a controller this can be:
// $this->request->getQuery('page', 'int'); // GET
// $this->request->getPost('page', 'int'); // POST
$currentPage = (int) $_GET["page"];

// The data set to paginate
$robots      = Robots::find();

// Create a Model paginator, show 10 rows by page starting from $currentPage
$paginator   = new PaginatorModel(
    array(
        "data"  => $robots,
        "limit" => 10,
        "page"  => $currentPage
    )
);

// Get the paginated results
$page = $paginator->getPaginate();

The $currentPage variable controls the page to be displayed. The $paginator->getPaginate() returns a $page object that contains the paginated data. It can be used for generating the pagination:

<table>
    <tr>
        <th>Id</th>
        <th>Name</th>
        <th>Type</th>
    </tr>
    <?php foreach ($page->items as $item) { ?>
    <tr>
        <td><?php echo $item->id; ?></td>
        <td><?php echo $item->name; ?></td>
        <td><?php echo $item->type; ?></td>
    </tr>
    <?php } ?>
</table>

The $page object also contains navigation data:

<a href="/robots/search">First</a>
<a href="/robots/search?page=<?= $page->before; ?>">Previous</a>
<a href="/robots/search?page=<?= $page->next; ?>">Next</a>
<a href="/robots/search?page=<?= $page->last; ?>">Last</a>

<?php echo "You are in page ", $page->current, " of ", $page->total_pages; ?>

适配器使用（Adapters Usage）¶

An example of the source data that must be used for each adapter:

<?php

use Phalcon\Paginator\Adapter\Model as PaginatorModel;
use Phalcon\Paginator\Adapter\NativeArray as PaginatorArray;
use Phalcon\Paginator\Adapter\QueryBuilder as PaginatorQueryBuilder;
use Phalcon\Paginator\Adapter\Sql as PaginatorSql;

// Passing a resultset as data
$paginator = new PaginatorModel(
    array(
        "data"  => Products::find(),
        "limit" => 10,
        "page"  => $currentPage
    )
);

// Passing an array as data
$paginator = new PaginatorArray(
    array(
        "data"  => array(
            array('id' => 1, 'name' => 'Artichoke'),
            array('id' => 2, 'name' => 'Carrots'),
            array('id' => 3, 'name' => 'Beet'),
            array('id' => 4, 'name' => 'Lettuce'),
            array('id' => 5, 'name' => '')
        ),
        "limit" => 2,
        "page"  => $currentPage
    )
);

// Passing a QueryBuilder as data

$builder = $this->modelsManager->createBuilder()
    ->columns('id, name')
    ->from('Robots')
    ->orderBy('name');

$paginator = new PaginatorQueryBuilder(
    array(
        "builder" => $builder,
        "limit"   => 20,
        "page"    => 1
    )
);

$paginator = new PaginatorSql(
    array(
        "sql" => "SELECT * FROM robots WHERE type = :type LIMIT :limit OFFSET :offset",
        "total_sql" => "SELECT COUNT(*) rowcount FROM robots WHERE type = :type",
            "bind" => ['type' => 'google'],
        "limit"   => 20,
        "page"    => 1
    )
);

页面属性（Page Attributes）¶

The $page object has the following attributes:

Attribute	Description
items	The set of records to be displayed at the current page
current	The current page
before	The previous page to the current one
next	The next page to the current one
last	The last page in the set of records
total_pages	The number of pages
total_items	The number of items in the source data

自定义适配器（Implementing your own adapters）¶

The Phalcon\Paginator\AdapterInterface interface must be implemented in order to create your own paginator adapters or extend the existing ones:

<?php

use Phalcon\Paginator\AdapterInterface as PaginatorInterface;

class MyPaginator implements PaginatorInterface
{
    /**
     * Adapter constructor
     *
     * @param array $config
     */
    public function __construct($config);

    /**
     * Set the current page number
     *
     * @param int $page
     */
    public function setCurrentPage($page);

    /**
     * Returns a slice of the resultset to show in the pagination
     *
     * @return stdClass
     */
    public function getPaginate();
}