跳转到内容
NextPDF

迁移指南

迁移指南

标题为“迁移指南”的章节

NextPDF 是一套面向 PHP 的 PDF 2.0 引擎。如果你已在使用其他库生成 PDF，迁移指南会把那套库的 API 映射到 NextPDF，并记录你会遇到的行为差异。本页是跨仓库索引：记录哪份指南带你从哪套库迁出、每份指南由哪个仓库维护，以及所有指南共用的统一模型。

因为本页只是索引，所以它不对任何指南做出行为宣称。每份指南都由各自的仓库维护。aggregate（聚合）流程由 aggregator（文档聚合器）负责，把各份指南拉取到本网站；在某份指南尚未导入之前，下方链接指向的是 placeholder（占位符）。每一项行为宣称都写在指南本身，并以仓库内的测试或固定的 ISO 32000-2 / CSS WG 条款佐证，而不是写在这里。

唯一的迁移模型

标题为“唯一的迁移模型”的章节

每一份 NextPDF 迁移指南都共用同一个如实模型，阅读每份指南时你都应该牢记：

  • 兼容，而非比特级完全相同。 NextPDF 与你准备迁出的那套库是各自独立的实现。你迁移过来的文档在意图上功能等价，而非像素或比特级完全相同。所有指南都不宣称可直接替换（drop-in），也不宣称 100% 兼容。
  • 覆盖率是测量得到的数量，不是一句断言。 当某份指南列出覆盖率数字时（例如 TCPDF 适配器），该数字取自仓库内矩阵中的功能完整度指标，意义上对应 ISO/IEC 25023 第 43 条——表示已覆盖方法的测量数量，而非全面保证。
  • 每份指南都会公开说明自己的行为差异。 每份指南都附有明确的差异表，并包含一节「不支持/无直接对应」。差异是已记录的引擎特性，不是缺陷。
  • 更换 renderer（渲染器）就需要重新审查。 迁移既是一次代码变更，也需要重新建立输出基准。每份指南都会说明如何测试这次迁移；视觉验收按文档逐一进行，由集成者负责。

迁移的形态

标题为“迁移的形态”的章节

这些指南分为两种形态。形态会说明你需要改动多少代码。

  • API 重写式迁移没有兼容 shim（兼容层）：每个调用点都要按照指南中的动词映射与选项映射重写。HTML 转 PDF 库的迁移（dompdf、mpdf）就是这种形态——它们直接以 NextPDF 的 Html pipeline 为目标。
  • 先直接替换、再逐步迁移式迁移会提供一个近乎源码兼容的适配器，所以最初的迁移只是一次最小范围的依赖包替换。之后，你再把调用点逐步迁移到现代 API，最后淘汰这个适配器。TCPDF 迁移就是这种形态，通过 nextpdf/compat-legacy 适配器进行。

指南与所属仓库对照

标题为“指南与所属仓库对照”的章节

下方每份指南都放在所属仓库的 docs/public/ 之下，再由 aggregator 拉取到本网站。所属仓库才是该指南行为宣称的权威来源；本索引只记录路由。

来源指南形态所属仓库页面
DompdfDompdf → NextPDF Html 管线API 重写nextpdf（核心）Dompdf 指南 dompdf（上游规划中）
mPDFmPDF → NextPDF 核心API 重写nextpdf（核心）mPDF 指南 mpdf（上游规划中）
TCPDF 6.xTCPDF → NextPDF（通过 compat-legacy 适配器）先直接替换、再逐步迁移nextpdf-compat-tcpdf 仓库，套件 nextpdf/compat-legacyTCPDF 指南 tcpdf-compat（上游规划中）

其中 dompdf 与 mpdf 指南放在核心仓库，因为它们面向核心引擎的 API，并由核心的 examples/ 提供佐证。tcpdf-compat 指南放在 compat-tcpdf 仓库，因为 nextpdf/compat-legacy 套件承载 TCPDF 的行为面，以及为该指南提供佐证的适配器测试。本索引放在 docs 本身，因为它跨越多个仓库，而且它不对其中任何一个做出行为宣称。

各份指南的用途

标题为“各份指南的用途”的章节
  • Dompdf → NextPDF（dompdf（上游规划中））——适用于在服务器端使用 dompdf/dompdf 的代码库。它把 loadHtml/render/output 以及 Options 配置键映射到 NextPDF 的 Html pipeline，并把 CSS 功能预期交由「仅限已验证」的 CSS 支持矩阵决定。没有 Dompdf 类 shim；每个调用点都要重写。
  • mPDF → NextPDF（mpdf（上游规划中））——适用于使用 mpdf/mpdf 的代码库。它把 WriteHTML/Output/AddPage 以及构造函数的配置数组映射到核心 API，并带有一个字体处理差异：NextPDF 通过单一字体目录加上 CSS 匹配来 resolve（解析），并始终进行子集化。没有 Mpdf 类 shim。
  • TCPDF → NextPDF（compat-legacy）（tcpdf-compat（上游规划中））——适用于希望把初始改动降到最低的 TCPDF 6.x 代码库。先安装适配器，在严格模式下对照仓库内的覆盖率矩阵审计你实际使用的接口，再把调用点从适配器迁出，然后在其上加入 PDF/UA-2 标记结构——这是 TCPDF 从未提供过的能力。这个适配器是脚手架，不是终点，也不是可直接替换（drop-in）的保证。

指南链接如何解析

标题为“指南链接如何解析”的章节

上面每个 [[…]] placeholder 都是一个前向引用，指向一个放在所属仓库 docs/public/migration/ 之下的页面，再由 aggregator 把该页拉取到本网站。目标 slug 遵循同一套约定：

/migration/<source>/

这里的 <source> token 是你要迁出的那套库的简称：dompdf、mpdf 或 tcpdf-compat 其中之一，如上方指南对照表所列。在目标页面尚未导入之前，它的链接只是 placeholder，无法解析。本索引不对任何目标指南做出行为宣称；它只记录路由，以及共用的迁移模型。

另请参阅

标题为“另请参阅”的章节
  • CSS 支持矩阵——dompdf 与 mpdf 指南把 CSS 功能预期交由这份「仅限已验证」的权威来决定。
  • Integration cookbook（集成范例集）——生态系统集成套件的跨仓库索引（这是另一回事：把引擎接上去，而不是迁移到它上面）。