SaloonPHP 分页插件中 currentPage 与 page 属性的正确使用方式

分页属性的设计原理

在 SaloonPHP 的分页插件中，currentPage 和 page 两个属性的设计体现了不同的分页计数逻辑。currentPage 采用从 0 开始的计数方式，而传统的 page 属性则采用从 1 开始的计数方式。

这种设计差异源于分页过程的内部机制：currentPage 表示当前已处理到的页面索引，而 page 则表示即将请求的下一页编号。当分页器初始化时，currentPage 默认为 0，表示尚未开始分页过程。

实际应用中的解决方案

在自定义分页逻辑时，如果需要向后端 API 传递页码参数（通常 API 期望从 1 开始的页码），正确的做法是使用 $this->currentPage + 1。这种做法既避免了使用已被标记为废弃的 page 属性，又符合大多数 API 的页码约定。

protected function applyPagination(Request $request): Request
{
    $request->query()->add('page', $this->currentPage + 1);
    
    if (isset($this->perPageLimit)) {
        $request->query()->add('limit', $this->perPageLimit);
    }
    
    return $request;
}

分页器的工作机制

SaloonPHP 的分页器实现了 PHP 的 Iterator 接口，这使得它可以直接在 foreach 循环中使用。分页过程遵循以下生命周期：

1. 初始化时 currentPage 设置为 0（或 startPage - 1）
2. 每次迭代时自动调用 rewind() 或 next() 方法
3. valid() 方法决定是否继续迭代
4. current() 方法返回当前页面的数据

理解这个生命周期有助于正确使用分页器，特别是在需要设置起始页码等高级场景时。

最佳实践建议

1. 始终使用 currentPage + 1 来构建 API 请求参数
2. 避免直接使用已被废弃的 page 属性
3. 如需设置起始页码，可以通过 setStartPage() 方法配合 rewind() 使用
4. 理解分页器的迭代器特性，可以更灵活地控制分页过程

通过遵循这些实践，开发者可以避免常见的分页陷阱，构建出更健壮的 API 分页逻辑。