PHP 兩款通用分頁類深度解析：模板驅動與陣列輸出模式

PHP 通用分頁類庫對比與實戰應用

分頁是 Web 開發基礎組件。本文深度解析兩種風格迥異的 PHP 分頁類：模板驅動型（Page 類）支援高度自定義 HTML 結構；陣列輸出型（Page_Link 類）專注邏輯計算，輸出結構化數據供前端渲染。兩者各有優勢，適用不同架構場景。

一、模板驅動型分頁類（Page）

特點：內建模板引擎，支援 {total}、{list}、{frist} 等佔位符，可通過 setTemplate()、setActiveTemplate() 靈活定制輸出。

核心功能

• 自動解析當前 URL 並保持其他查詢參數
• 支援首頁、上一頁、數字頁碼（可配置顯示條數）、下一頁、尾頁、跳轉輸入框
• 提供 getOffset() 直接獲取 SQL LIMIT 偏移量
• 屬性訪問攔截 __get('limit') 返回 LIMIT offset, size

使用示例

<?php
$page = new Page();
$page->init(1000, 20); // 總記錄 1000，每頁 20
$page->setTemplate('<div class="pager">{frist}{pre}{list}{next}{last}{goto}</div>');
$page->setActiveTemplate('<span class="current">{text}</span>');
$page->setNotActiveTemplate('<a href="{url}">{text}</a>');
echo $page->show();

// SQL 查詢
$offset = $page->getOffset();
// 或直接用 $page->limit
$sql = "SELECT * FROM articles LIMIT {$page->limit}";
?>

二、陣列輸出型分頁類（Page_Link）

特點：不輸出 HTML，返回結構化陣列，包含 url、name、no、attr 等鍵值，適合 API 接口、前後端分離、自定義模板引擎（Smarty/Twig/Blade）場景。

核心方法

• make_page($total, $act_page, $url, $param)：基礎分頁，返回頁碼陣列
• make_page_with_total(...)：包含總頁數信息
• make_page_with_points(...)：支援省略號（...）、首尾頁、上下頁、自定義樣式（</>、<</>>）

智能頁碼分組算法

類內部實現了 Calculation_Min_Max()，根據總頁數、最大顯示頁碼數（page_max）、當前頁自動計算顯示範圍：

• 總頁數 ≤ 最大顯示：全部顯示
• 當前頁靠近首尾：固定顯示首/尾段
• 當前頁在中間：以當前頁為中心對稱顯示

使用示例（配合模板引擎）

<?php
$pager = new Page_Link();
$pager->page_max = 8;   // 最多顯示 8 個頁碼
$pager->length   = 15;  // 每頁 15 條
$pager->isNextPage = true;
$pager->isFirstPage = true;

$result = $pager->make_page_with_points(
    $totalCount,    // 總記錄數
    $currentPage,   // 當前頁
    $baseUrl,       // 基礎 URL
    8,              // 最大顯示頁碼
    2,              // 樣式：< / >
    'page'          // 分頁參數名
);

// 模板渲染 (Twig 示例)
/*
<nav class="pagination">
  {% for item in result %}
    {% if item.url %}
      <a href="{{ item.url }}" {% if item.attr == 'current' %}class="current"{% endif %}>{{ item.name }}</a>
    {% else %}
      <span class="current">{{ item.name }}</span>
    {% endif %}
  {% endfor %}
</nav>
*/
?>

三、兩款類對比與選型建議

四、現代化改進建議

1. PSR-4 自動加載：將類放入 src/Pagination/，配置 composer.json。
2. 介面契約：定義 PaginationInterface，支援多種實現互換。
3. URL 生成器解耦：注入 UrlGeneratorInterface，適配 Laravel/ThinkPHP/Symfony 路由。
4. 輸出 DTO：用 PaginationResult 物件替代陣列，提供類型提示。
5. 單元測試：覆蓋邊界值（第 1 頁、最後頁、總頁數 < 每頁數等）。