TCPDF 兼容性开发者指南

快速概览

兼容性适配器是一个迁移层。它应让旧版行为保持可见，而不是将其隐藏。你可以用它维持应用程序运行，同时将高价值路径迁移到原生 NextPDF API。

当你维护 TCPDF 形态的旧版代码、扩展适配器覆盖范围，或规划分阶段迁移到原生 NextPDF API 时，请使用本指南。

架构边界

分层	拥有者	职责	不要放在这里
旧版应用程序	应用程序	在迁移期间维持现有 TCPDF 形态的调用继续运行。	应使用原生 NextPDF API 的新 PDF 功能。
适配器外壳	`nextpdf/compat-legacy`	公开 `TCPDF` 形态的类和共享的兼容性状态。	大型方法群组或转换逻辑。
关注点 trait	`nextpdf/compat-legacy`	对旧版方法群组进行分类：文本、字体、图像、安全性、表单、页面。	跨群组的输出策略。
桥接类	`nextpdf/compat-legacy`	转换旧版参数、目的地、颜色、单位与格式。	业务专属行为。
核心引擎	`nextpdf/nextpdf`	生成原生文档。	旧版兼容性承诺。

运行时生命周期

阶段	行为	开发者动作
引导启动	可选的旧版引导程序会公开兼容性名称。	只在旧版代码预期存在 TCPDF 符号的位置使用。
构造	旧版构造函数参数会被转换为核心文档配置。	迁移期间保持构造函数输入稳定。
方法调用	受支持的方法会通过关注点与桥接映射到 NextPDF 行为。	在假设行为等价之前，先检查方法覆盖范围。
不支持的功能	不受支持的行为会抛出明确的兼容性异常。	替换该调用，或将其隔离在应用程序代码后方。
输出	输出桥接会将旧版目的地行为映射到 NextPDF 输出。	验证文件名与存储根目录。

迁移盘点

先收集应用程序中的每一个 TCPDF 方法调用。改变行为之前，先对每个调用进行分类。

分类	含义	动作
支持的适配器方法	方法已记录为受支持，并有测试覆盖。	暂时保留，后续触及该区域时再迁移。
部分支持的适配器方法	方法存在，但行为尚未完全匹配旧版 TCPDF。	添加 fixture 测试，并手动验证输出。
明确不支持的方法	适配器会抛出兼容性异常。	改用原生 NextPDF，或移除该功能。
业务专属包装	应用程序已封装 TCPDF 调用。	先迁移封装内部。
合规敏感的调用	签名、加密、标记、PDF/A、无障碍或发票流程。	迁移到原生 NextPDF API，并执行专项验证。

适配器贡献模式

在承载该行为的最小方法群组中加入兼容性支持。

变更类型	在何处实现	必需测试
文本输出方法	`Concerns\AdaptsTextOutput` 或字体关注点。	旧版 fixture，并添加原生输出断言。
页面或边距方法	页面、定位或边距关注点。	坐标转换与页面状态测试。
图像或绘图方法	图像、绘图、颜色或渐变关注点。	输入验证与 visual/structural 输出测试。
输出目的地	`OutputBridge`。	目的地映射与不安全路径测试。
不支持的功能	异常工厂或方法覆盖表。	异常类型与消息测试。

当某个关注点 trait 承载该群组时，不要把大型方法直接加入适配器外壳。

原生迁移模式

先用适配器稳定行为，再将已稳定的工作流程迁移到原生 API。

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

将迁移视为一系列小规模的行为变更。某个高风险区段迁移到原生 API 后，页面仍可继续使用适配器。

扩展点

扩展点	用途	约束
`AdaptationConfig`	在迁移期间控制适配器行为。	保持默认值经过审查且明确。
关注点 trait	将方法按群组组织，例如文本、表单、图像或安全性。	将方法加入适当的关注点，而不是适配器外壳。
桥接类	将旧版参数形态转换为核心值。	确保桥接行为持续受到迁移测试覆盖。
`CompatAdapterInterface`	提供供工具使用的适配器级别抽象。	在新代码中，不要用它取代原生核心契约。
方法覆盖表	面向开发者的支持台账。	支持状态变更时同步更新。

迁移工作流程

安装适配器，并在不做修改的情况下运行旧版测试套件。
打开方法覆盖，并对每个被调用的方法进行分类。
先替换不受支持的方法。
将高流量或合规敏感的路径迁移到原生核心 API。
为每个已迁移的方法群组添加 fixture 覆盖范围。
当没有应用程序入口点依赖引导别名时，移除这些别名。

失败处理

失败	应在何处处理	建议的响应
不受支持的方法	适配器异常。	替换该调用，或将其隔离在应用程序适配器后方。
版面仅部分对等	迁移测试与视觉审查。	推出前先记录已接受的差异。
不安全的输出目的地	`OutputBridge` 与应用程序存储策略。	拒绝不安全的路径，并优先使用原生输出 API。
安全性功能不一致	原生迁移计划。	不要为受监管输出上线仅依赖兼容性的行为。
引导别名冲突	应用程序引导程序。	移除全局别名，或将其限定在旧版入口点范围内。

安全的默认值

关注点	默认值	何时覆盖
不受支持的方法	抛出明确异常。	在生产环境中不要弱化这一行为。
旧版默认值	集中在 `LegacyDefaults`。	只在迁移行为已知时才覆盖。
输出映射	通过 `OutputBridge`。	迁移后改用原生输出 API。
覆盖范围来源	方法覆盖页面与测试。	每次适配器升级后，重新运行覆盖范围检查。
严格模式	在迁移审核期间保持启用。	只在有记录的旧版兼容性窗口内才停用。

测试检查清单

为每个已迁移的方法群组保留一份旧版 fixture。
在替换旧版方法之前，先添加一个原生 NextPDF 测试。
断言不受支持的方法会抛出有记录的异常。
当逐字节相等并非务实的迁移目标时，改为比较输出结构。
新增或变更适配器方法后，运行方法覆盖范围检查。
为旧版代码使用的每个输出目的地添加存储路径测试。