Skip to content

升級指南

TCPDF-Next 目前處於 1.x 版本線。本頁說明版本控制策略及如何保持最新。

語意化版本控制

TCPDF-Next 遵循 Semantic Versioning 2.0.0

版本變更含義可安全更新?
修訂版 (1.0.x)錯誤修正、文件更新、內部重構是 — 完全向後相容
次版本 (1.x.0)新功能、非破壞性新增是 — 現有程式碼無需變更
主版本 (x.0.0)破壞性 API 變更請先閱讀遷移指南

在 1.x 系列期間,公開 API 視為穩定。任何破壞性變更將保留至下一個主版本,並附帶詳細遷移指南。

查看變更紀錄

升級前,請檢閱 GitHub 上的 CHANGELOG。每個版本列出:

  • Added — 新功能與類別
  • Changed — 現有行為的修改
  • Deprecated — 將在下一個主版本移除的 API
  • Fixed — 錯誤修正
  • Security — 安全性修補(請立即升級)

透過 Composer 更新

bash
# 更新至約束範圍內的最新相容版本
composer update yeeefang/tcpdf-next

# 或釘選特定版本
composer require yeeefang/tcpdf-next:^1.2

更新後,執行測試套件以確認一切正常:

bash
composer test

從其他函式庫遷移

從舊版 TCPDF

TCPDF-Next 不是 fork,而是從零開始的完全重寫。主要差異:

  • 靜態設定常數改為型別化列舉與值物件。
  • 消除全域狀態 — 每個 Document 實例獨立運作。
  • 所有類別盡可能使用 readonly,嚴格 declare(strict_types=1)
  • 需要 PHP 8.5+(參見為什麼選擇 PHP 8.5?)。

從 FPDF / FPDI

cell/multiCell/text/write 等方法刻意保留相似的命名,學習曲線極低。主要差異:

  • 具名參數與列舉取代位置型整數旗標。
  • 輸出使用 OutputDestination 列舉而非單字元字串。
  • 字型管理透過 FontConfig 處理,而非手動放置檔案。

從 Dompdf / wkhtmltopdf

如果你習慣 HTML 轉 PDF,請參考 Artisan 套件,它在 TCPDF-Next Core 之上提供完整的 CSS3 渲染管線。對於程式化 PDF 建構,基本用法中描述的 API 驅動方式比 HTML 方式更高效且可預期。

以 LGPL-3.0-or-later 授權釋出。