跳转到内容
NextPDF

NextPDF compat-legacy 概览

概览

标题为“概览”的章节

nextpdf/compat-legacy 是一套 TCPDF 兼容的替代方案：它是在 NextPDF PDF 2.0 引擎之上公开 TCPDF 6.x 公共 API 的兼容层。它只有一个目的：让已经依赖 TCPDF 6.x 的代码库无需重写即可运行在 NextPDF 引擎上，从而按文件逐步迁移，而不是一次性完成全部迁移。

它并非 TCPDF 的分支（fork），也不会宣称在行为上完全一致。它是一套保留 TCPDF 调用签名的独立实现。更准确地说：它通过直接委派覆盖了约 120 个受调查的 TCPDF 6.x 方法中的 94 个，其余方法则带有已记载的行为差异（请参阅 /integrations/tcpdf-compat/method-coverage/）。

它是什么

标题为“它是什么”的章节
  • 一项迁移辅助工具。 此软件包是 NextPDF compat 系列的一部分。它的目标是缩短摆脱旧版 PDF 库的路径，而不是成为永久依赖。请把它视为在采用现代 API 后会移除的脚手架。
  • 一个 API 表面的适配器。 它提供 TCPDF 的类名、方法名、参数顺序，以及 6.2.13 的默认值。调用会被委派给一个 NextPDF\Core\Document 实例。
  • 一套独立的洁净室（clean-room）实现。 没有任何 TCPDF 源代码、构建产物、字体数据或其他可受著作权保护的表达内容被复制或转译到此软件包中。TCPDF 这个名称仅用于互通性识别。正式声明位于软件包的 NOTICE 文件中。

它不是什么

标题为“它不是什么”的章节
  • 它并非一个输出字节完全相同的「即插即用替代品」。对于已委派的方法，可见结果是兼容的，但渲染出的 PDF 字节会有所不同，因为底层引擎是另一套独立的 PDF 2.0 实现。
  • 它并非「100% 与 TCPDF 兼容」。有一组边界明确的方法会接受引擎并不遵循的旧版参数，或是完全不做任何事。这些情况均已列举并测试——请参阅 /integrations/tcpdf-compat/method-coverage/。
  • 它本身并非一项签名或归档产品。数字签名与 PDF/A 归档符合性受限于商业版的 NextPDF 版本。本文档并未提出任何经认证、保证或具法律效力签名的主张。

为何要通过兼容层进行迁移

标题为“为何要通过兼容层进行迁移”的章节

在大型应用程序中重写每一个 TCPDF 调用风险很高，也难以渐进交付。兼容层让你能够：

  1. 替换依赖项并运行你现有的测试套件，找出哪些部分已经可以原封不动地运行。
  2. 使用严格模式执行一次审计，列举出每一处无法被完全重现的 TCPDF 行为。
  3. 逐一将这些调用点迁移到现代的 NextPDF API，同时让应用程序在整个过程中都保持可交付状态。

最终状态是采用现代的 NextPDF\Core\Document API，并移除兼容层。完整策略请参阅 /integrations/tcpdf-compat/migration/。

在 NextPDF 引擎上你能获得什么

标题为“在 NextPDF 引擎上你能获得什么”的章节

当一个 TCPDF 调用被委派时，它会在 PDF 2.0（ISO 32000-2）引擎上运行，可使用 AES-256 标准处理程序加密，并在整个适配器中具备 PHPStan Level 10 的类型安全。输出一律写为 PDF 2.0；适配器无法向下映射到较旧的 PDF 版本（请参阅 /integrations/tcpdf-compat/method-coverage/ §4）。

适配器强化了 TCPDF 6.2.13 中若干长期存在的陷阱：

旧版行为适配器行为
Error() 会调用 die() 并悄悄终止进程Error() 会抛出 RuntimeException——可观察且可捕获
可能从标记语言执行 PHP 的 HTML 方法该逃生通道已被禁用——标记语言无法触发 PHP 执行
Output() 会直接输出（echo），可能损坏工作进程的输出缓冲区输出会通过一个安全的目标桥接层导向
未受保护的 header/footer 递归已加上递归防护

范围与版本

标题为“范围与版本”的章节

兼容层随 core 发行版提供（nextpdf/compat-legacy，需要 nextpdf/core ^3.0）。通过标准处理程序的加密在 core 中即可使用。数字签名与 PDF/A 归档符合性需要商业版的 NextPDF 版本；适配器会公开入口点，但 core 路径本身并非一项签名产品。精确说明请参阅 /integrations/tcpdf-compat/security-and-operations/。

接下来该看哪里

标题为“接下来该看哪里”的章节
  • /integrations/tcpdf-compat/install/——安装软件包并验证引擎链接。
  • /integrations/tcpdf-compat/quickstart/——创建第一份可运行且有测试支撑的文档。
  • /integrations/tcpdf-compat/method-coverage/——每个 TCPDF 方法在此处的确切行为。
  • /integrations/tcpdf-compat/migration/——按文件逐步迁移的策略。
  • /integrations/tcpdf-compat/configuration/——严格模式与适配器配置。
  • /integrations/tcpdf-compat/production-usage/——在负载下以及在工作进程中运行适配器。
  • /integrations/tcpdf-compat/security-and-operations/——加密、签名状态与强化。
  • /integrations/tcpdf-compat/troubleshooting/——常见的迁移失败及其修复方式。
  • /integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/——将外观（facade）接入应用程序并注册全局类别名。

另请参阅

标题为“另请参阅”的章节
  • docs/TCPDF_COVERAGE.md——权威覆盖范围对照表（位于仓库中）
  • 软件包 NOTICE——独立实现声明