升級指南
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 方式更高效且可預期。