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