TCPDF (已弃用 → 请使用 tc-lib-pdf)

---

概述

TCPDF 是一个纯 PHP 库，用于在应用程序代码中直接生成 PDF 文档和条形码。

它已在许多 PHP 技术栈中广泛使用，并且仍然提供完整的功能集，包括文本渲染、页面排版、图形、签名、表单和面向标准的输出。

包	tecnickcom/tcpdf
作者	Nicola Asuni info@tecnick.com
许可证	GNU LGPL v3（参见 LICENSE.TXT）
网站	http://www.tcpdf.org
源代码	https://github.com/tecnickcom/TCPDF

---

架构：基于 tc-lib-pdf 的兼容性外观

从本版本开始，TCPDF 类不再包含其自身的 PDF 引擎。 它是一个兼容性外观：每个公开的 TCPDF 方法都是一个薄包装器，将实际的 PDF 生成委托给现代化的 tecnickcom/tc-lib-pdf 引擎（\Com\Tecnick\Pdf\Tcpdf），同时有一个小型的内部状态层来重现遗留的有状态光标和页面模型（当前 X/Y 坐标、边距、字体、颜色、自动分页、页眉/页脚）。

这在实践中意味着：

• 公开 API 保持不变。 所有 291 个公开方法的签名（名称、参数、默认值）与旧版 TCPDF 完全相同；现有的集成可以继续像以前一样调用 new TCPDF(...)、AddPage()、SetFont()、Cell()、writeHTML()、Output()。
• 渲染由现代引擎完成。 文本布局、HTML/CSS、字体、图形、条形码、加密、签名和输出生成都来自 tc-lib-* 库。
• 每个方法的委托状态都有文档记录。 参见 MAPPING.md 了解每个公开方法的状态（delegated、adapter、shim、intentional-noop、blocked）及说明；该表格会根据类进行机器验证。
• 输出在结构上等效，但并非字节完全一致。 文档的页面大小和内容渲染相同，但现代引擎的换行和字体度量可能与旧版实现略有不同（长文档的分页可能会提前或延后一页）。
• 某些旧版行为有意不再重现。 在现代引擎的模型优先的情况下，一些功能被移除或更改（旧版字体定义、EPS/AI 矢量导入、始终开启的流压缩、基于策略的本地文件访问、各种空操作）。完整列表请参见下文的 重大变更 以及 MAPPING.md 中的每个方法说明。

---

弃用通知

TCPDF 已弃用，目前仅处于维护模式。

活跃的功能开发已迁移至 tc-lib-pdf，这是其现代化且模块化的继任者。

对于新项目，请使用 tecnickcom/tc-lib-pdf。本仓库仍将保留，以支持遗留系统和关键兼容性修复。

迁移路径

• 新项目：安装 tecnickcom/tc-lib-pdf。
• 现有 TCPDF 用户：继续在当前生产工作负载中使用 TCPDF，并分阶段进行迁移。
• 寻求现代化架构、Composer 优先设计以及更强类型安全性的团队应优先选择 tc-lib-pdf。

字体资源迁移

TCPDF 已将字体加载迁移至 tc-lib 字体栈（详见下文“重大变更”）。

• tecnickcom/tc-lib-pdf 是 Composer 入口点。
• 字体资源由 tecnickcom/tc-lib-pdf-font 提供，并可在 vendor/tecnickcom/tc-lib-pdf-font/target/fonts/ 路径下找到。
• 仓库随附的 fonts/ 资源已移除；TCPDF 现在从 tc-lib 资源中解析捆绑字体。

受影响用户：

• 依赖本地 fonts/ 文件但没有 Composer 依赖的部署。
• 对 K_PATH_FONTS 的假设与仓库相对字体文件夹相关联的应用程序。
• 使用自定义或生成的字体定义并期望仅使用 PHP 描述符文件的集成。

自定义字体使用迁移方法：

1. 使用 Composer 安装依赖项。
2. 确保 tc-lib 字体资源在 vendor/tecnickcom/tc-lib-pdf-font/target/fonts/ 路径下可用。
3. 继续使用 TCPDF 中的 SetFont()/AddFont()，但需验证每个自定义字体系列是否从 tc-lib 资源或您的显式字体路径中解析。
4. 更新部署打包，确保 vendor/ 字体资源随生产环境一同部署。

字体生成步骤（Makefile）：

1. 运行 make deps 安装 Composer 依赖项并初始化 tc-lib 字体资源。
2. 运行 make fonts 仅在字体缺失时初始化字体。
3. 运行 make fonts-rebuild 强制完全重建字体资源。

预期生成的资源标记文件：

• vendor/tecnickcom/tc-lib-pdf-font/target/fonts/core/helvetica.json

兼容性说明：

• TCPDF 会检查已配置的字体路径和 tc-lib 字体资源。
• tc-lib 的 JSON 字体描述符可被 TCPDF 的 AddFont() 路径接受。
• 不再支持旧版 PHP 字体描述符（fontname.php + fontname.z） （详见下文“重大变更”）；请改用 tc-lib-pdf-font 导入器转换原始 TTF/OTF 文件。

示例：

require __DIR__.'/vendor/autoload.php';

// Optional: override only if you need a non-default path.
define('K_PATH_FONTS', __DIR__.'/vendor/tecnickcom/tc-lib-pdf-font/target/fonts/');

$pdf->SetFont('helvetica', '', 11);

安全迁移清单：

1. 在 Composer 中引入 tecnickcom/tc-lib-pdf 并安装依赖项。
2. 确认字体资源目录存在于 vendor/tecnickcom/tc-lib-pdf-font/target/fonts/ 下。
3. 运行 PDF 冒烟测试，检查页眉、正文文本、粗体/斜体、RTL 文本和 Unicode 文本。
4. 验证是否存在需要依赖仓库 fonts/ 文件的运行时路径假设。
5. 移除指向已删除目录的旧版 K_PATH_FONTS 覆盖设置。
6. 对代表性文档重新运行回归输出比较。

为何迁移至 tc-lib-pdf

• 现代化架构：模块化库和更清晰的组件边界提升了可维护性。
• 更好的可扩展性：无需修改庞大的旧版核心代码，即可更轻松地添加新功能。
• 更强的工具适配性：现代化的包结构更适配静态分析、CI 和自动化测试。
• 降低长期风险：减少与旧版 API 相关的技术债务，并支持 PHP 生态系统的持续发展。
• 提高交付速度：团队能够更顺畅地实现和发布新的 PDF 功能。

迁移仍需进行规划和回归检查，以确保现有文档的渲染一致性。

---

重大变更

与逐行模拟旧版行为相比，门面更倾向于现代化引擎模型，具体体现在以下方面。每项变更都是经过深思熟虑并记录在案的契约变更：

1. 字体模型。 字体完全通过 tc-lib-pdf-font 堆栈解析： 在 K_PATH_FONTS（vendor/tecnickcom/tc-lib-pdf-font/target/fonts/，通过 make fonts 生成）下发现的 JSON 定义文件。 旧版 TCPDF 字体定义格式（fontname.php + fontname.z / fontname.ctg.z）不受支持，且不会在运行时进行转换：

   • SetFont()/AddFont() 接受 tc-lib 字体堆栈已知的字体系列（核心字体、DejaVu、FreeFont、CID-0 等），或通过字体文件参数指定的 tc-lib JSON 格式定义文件。
   • 仅旧版捆绑的字体（如 aefurat、aealarabiya）不可用；请求这些字体会抛出字体异常。请使用具有同等覆盖范围的 tc-lib 字体（例如，阿拉伯语使用 freeserif/dejavusans），或通过 tc-lib-pdf-font 导入器导入原始 TTF/OTF。
   • 字体子集化、字距调整和度量遵循 tc-lib 的实现。

   有关详细的迁移步骤，请参见上文的“迁移字体资源”。

2. 流压缩始终启用。 setCompression(false) 不起作用；引擎始终压缩内容流。

3. EPS/AI 矢量导入已移除。 现代引擎没有 PostScript 解释器，因此 ImageEps() 会忽略 EPS/AI 输入。请将 EPS/AI 图形转换为 SVG（例如 inkscape file.eps --export-filename=file.svg）并改用 ImageSVG()。为方便起见，ImageEps() 会将 SVG 和光栅文件名分发到现代处理路径。

4. RC4 加密仅为旧版兼容。 setProtection() 模式 0/1 仍然有效，但引擎已弃用 RC4；推荐使用 AES 模式（2/3）。setProtection() 必须在添加第一页之前调用。

5. 资源加载基于策略。 引擎限制外部资源（图像、字体、SVG、导入的 PDF）的加载位置：本地读取仅限于可信目录的允许列表，远程（HTTP/HTTPS）读取默认禁用。旧版 setAllowLocalFiles() 开关不再放宽访问限制；策略由配置常量驱动（参见 资源加载安全）。

较小的有意无操作（磁盘缓存、setDocInfoUnicode()、页眉 XObject 模板缓存、矢量图像光栅化切换等）及其原因在 MAPPING.md 中列出。

资源加载安全

外部资源通过 tc-lib-pdf / tc-lib-file 提供的沙盒文件助手进行获取。该沙盒强制执行两个独立的允许列表，均可通过 define() 常量进行配置（由 tcpdf_autoconfig.php 读取，可在 config/tcpdf_config.php 中或自动配置运行前覆盖）：

常量	类型	默认值	用途
K_ALLOWED_PATHS	string[]	[]	额外的受信任本地目录前缀，合并到内置默认值之上。
K_ALLOWED_HOSTS	string[]	[]	允许 HTTP/HTTPS 加载的受信任远程主机名。为空时保持远程加载禁用状态。
K_MAX_REMOTE_SIZE	int	52428800	单个远程下载的字节上限（50 MiB）。
K_CURLOPTS	array	[]	合并到 cURL 默认值上的额外 CURLOPT_* => value 键值对。

本地读取。内置允许列表始终涵盖系统临时目录、K_PATH_MAIN、捆绑的 vendor/tecnickcom/ 目录、当前工作目录、K_PATH_FONTS、K_PATH_IMAGES 以及运行脚本所在的目录。K_ALLOWED_PATHS 仅用于扩展此集合——路径通过 realpath() 解析，因此不存在或无法解析的条目会被静默忽略，路径遍历/符号链接技巧会折叠为其规范前缀。无法读取内置根目录之外的内容。

远程读取。远程 URL 加载默认是关闭的——这是在渲染不可信 HTML/标记时防范 SSRF 的最重要防御措施。要启用，需在 K_ALLOWED_HOSTS 中列出您信任的确切主机名。TLS 证书验证和重定向处理由上游强制执行，无法通过 K_CURLOPTS 放宽。

// Enable downloads from two trusted CDNs, cap them at 10 MiB, and add a custom timeout.
define('K_ALLOWED_HOSTS', ['cdn.example.com', 'assets.example.org']);
define('K_MAX_REMOTE_SIZE', 10 * 1024 * 1024);
define('K_CURLOPTS', [CURLOPT_TIMEOUT => 15]);
// Allow reading shared assets from outside the install tree.
define('K_ALLOWED_PATHS', ['/var/www/shared/assets/']);

文档加密是一个独立的问题：setProtection()（上文第 4 项）控制 PDF 权限标志以及密码/公钥加密，不受这些资源加载常量的影响。

---

要求

• PHP 8.2 或更高版本
• ext-curl

某些工作流程中用于实现更丰富输出的可选扩展：gd（自动光栅格式转换）、zlib。

---

开发与质量保证

此仓库提供了一个真实的验证工具：

命令	用途
make deps	安装 Composer 依赖项、工具，并初始化 tc-lib 字体资源
make qa	完整检查：mago 代码检查 + 静态分析 + PHPUnit 测试套件
make test	运行 PHPUnit 测试套件 (test/)
make smoke	以无头模式运行所有 68 个示例脚本，并验证生成的 PDF 文档
make inventory	重新生成公共方法清单报告
make mapping	验证委托映射并重新生成 MAPPING.md

示例冒烟测试运行器 (scripts/example_smoke.php) 需要 pdfinfo（poppler-utils），并将任何警告、通知或弃用提示视为失败。那些涉及已声明的重大变更的示例可以作为预期失败进行跟踪，并记录原因（目前无此类示例：所有 68 个示例均通过）。

---

第三方字体

第三方捆绑字体资源通过 tecnickcom/tc-lib-pdf-font 提供，位于 vendor/tecnickcom/tc-lib-pdf-font/target/fonts/ 目录下。

TCPDF 不再随附存储库本地的 fonts/ 目录。

有关详细信息，请参阅 tecnickcom/tc-lib-pdf-font 附带的通知。

---