Pagerfanta分页库使用指南：从基础到高级功能详解

前言

在Web开发中，数据分页是一个常见需求。Pagerfanta作为PHP生态中优秀的分页解决方案，提供了灵活而强大的分页功能。本文将全面介绍Pagerfanta的核心用法，帮助开发者掌握这一工具。

基础用法

Pagerfanta的基本使用流程包含三个步骤：

1. 创建适配器(Adapter)封装待分页数据
2. 实例化Pagerfanta对象
3. 配置分页参数并获取结果

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

// 使用数组适配器
$adapter = new ArrayAdapter([]);
$pagerfanta = new Pagerfanta($adapter);

// 获取当前页结果（默认返回第一页的10条数据）
$currentPageResults = $pagerfanta->getCurrentPageResults();

简化初始化

Pagerfanta提供了静态构造方法createForCurrentPageWithMaxPerPage，可以简化初始化过程，自动处理参数顺序：

use Pagerfanta\Adapter\NullAdapter;
use Pagerfanta\Pagerfanta;

$adapter = new NullAdapter(100);
// 参数依次为：适配器、当前页码、每页最大数量
$pagerfanta = Pagerfanta::createForCurrentPageWithMaxPerPage($adapter, 2, 5);

分页参数配置

每页显示数量

通过setMaxPerPage方法设置每页显示数量，getMaxPerPage获取当前值：

$pagerfanta = new Pagerfanta(new NullAdapter(10));
$pagerfanta->setMaxPerPage(3);  // 设置每页显示3条
$perPage = $pagerfanta->getMaxPerPage();  // 获取当前设置

注意：

• 必须在获取结果前设置
• 参数必须大于0，否则抛出LessThan1MaxPerPageException

当前页码设置

通过setCurrentPage设置当前页码，getCurrentPage获取当前值：

$pagerfanta = new Pagerfanta(new NullAdapter(30));
$pagerfanta->setCurrentPage(3);  // 设置当前为第3页
$currentPage = $pagerfanta->getCurrentPage();  // 获取当前页码

异常处理：

• 页码小于1抛出LessThan1CurrentPageException
• 超出最大页码抛出OutOfRangeCurrentPageException

分页状态判断

是否需要分页

haveToPaginate方法判断数据是否需要分页：

$pagerfanta = new Pagerfanta(new NullAdapter(30));

$pagerfanta->setMaxPerPage(10);
$needPaginate = $pagerfanta->haveToPaginate();  // 返回true

$pagerfanta->setMaxPerPage(50);
$needPaginate = $pagerfanta->haveToPaginate();  // 返回false

获取总页数

getNbPages方法获取分页后的总页数：

$pagerfanta->setMaxPerPage(10);
$totalPages = $pagerfanta->getNbPages();  // 30条数据，每页10条，返回3

高级功能

最大页数限制

通过setMaxNbPages限制最大显示页数，resetMaxNbPages重置限制：

$pagerfanta->setMaxNbPages(2);  // 限制最多显示2页
$pagerfanta->resetMaxNbPages();  // 取消限制

页面导航

判断和获取前后页：

// 判断是否有前一页/后一页
$hasPrev = $pagerfanta->hasPreviousPage();
$hasNext = $pagerfanta->hasNextPage();

// 获取前一页/后一页页码
if ($pagerfanta->hasNextPage()) {
    $nextPage = $pagerfanta->getNextPage();
}

适配器访问

获取底层适配器实例：

$adapter = $pagerfanta->getAdapter();

自动分页迭代器（4.1+）

处理大数据集时，可使用autoPagingIterator避免内存溢出：

$pagerfanta = new Pagerfanta(new NullAdapter(100));
$pagerfanta->setMaxPerPage(10);

foreach ($pagerfanta->autoPagingIterator() as $item) {
    // 逐页处理每个项目
}

最佳实践

1. 参数顺序：总是先设置MaxPerPage再设置CurrentPage
2. 异常处理：捕获可能的分页参数异常
3. 性能优化：大数据集使用自动分页迭代器
4. UI集成：结合模板引擎实现分页UI

总结

Pagerfanta提供了全面的分页解决方案，从基础的分页功能到高级的自动分页处理，能够满足各种复杂场景的需求。通过本文的介绍，开发者应该能够熟练地在项目中使用Pagerfanta实现高效、稳定的分页功能。