TCPDF 兼容 API 参考

概览

本 nextpdf/compat-legacy 包提供一个主要类 NextPDF\Compat\Tcpdf\TCPDF，它镜像 TCPDF 6.x 的公开 API，但会在现代 NextPDF 引擎上绘制输出。它还提供一组精简的支持组件：用于全局类名别名的 LegacyBootstrap、一组 AdaptationConfig/LegacyDefaults 配置接口、内部桥接类（输出、构造函数、颜色、单位、页面格式），以及兼容性异常。它是迁移辅助工具，并非长期依赖项。完整的旧版方法状态列在方法涵盖表中。本页说明应用程序代码应当有意依赖的接口。

**从这里开始：**如果你刚接触这个包，先构造 NextPDF\Compat\Tcpdf\TCPDF，照常调用你熟悉的 TCPDF 方法（AddPage()、SetFont()、Cell()），最后用 Output($name, $dest) 收尾。这个类几乎是下方所有内容的入口。可执行的入门示例见常见任务一节。

常见任务

这些是使用此包时最常见的实际任务。每个区块都已对照适配器源码验证，可直接运行。

用熟悉的 TCPDF 调用生成 PDF，并将其捕获为字符串（用于队列、HTTP 响应或存储）：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

作用：通过 TCPDF 风格的适配器构造一份 PDF 2.0 文档，并返回原始字节（%PDF...），因为目的地 'S' 会经由 OutputBridge 路由到 Document::getPdfData()，而不是直接 echo 输出，因此在 worker 或控制器中使用是安全的。

只要在启动时注册一次全局别名，就能不改任何源码，直接运行既有的 new \TCPDF(...) 代码：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

作用：enableAliases() 会以幂等方式注册 \TCPDF（以及 \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES 等辅助类），但只会在这些名称尚未定义时注册，因此未修改的旧版代码会在适配器上运行。

通过暴露每一个被静默丢弃的 TCPDF 参数来审计一次迁移：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

作用：开启 setStrictMode(true) 后，任何无法重现 TCPDF 行为的调用都会抛出 TcpdfNotImplementedException，并指出被忽略的参数。这会把静默降级转化为一份迁移待办清单（只在审计流程中执行，绝不可用于生产环境）。

主要适配器

这张表是适配器的正式接口。当你需要查阅所构造的类（TCPDF）、它的严格模式与底层访问方法，以及它实现的契约时，请查这张表。

符号	参数	默认行为	返回	抛出或失败条件	备注
`NextPDF\Compat\Tcpdf\TCPDF`	构造函数参数通过 `ConstructorBridge` 沿用旧版 TCPDF 的参数形状。	创建一个由 NextPDF 文档支撑的适配器。	`TCPDF`	构造函数验证或不支持功能的异常。	用于迁移期间，不适用于新编写的原生 NextPDF 代码。
`TCPDF::getDocument()`	无。	返回底层的 NextPDF 文档。	`NextPDF\Core\Document`	预期无。	供必须混用旧版与原生调用的迁移代码使用的底层访问方法。
`TCPDF::getUnitConverter()`	无。	返回由旧版单位创建的转换器。	`UnitConverter`	预期无。	用于迁移诊断，而非一般应用程序代码。
`TCPDF::setStrictMode(bool $enabled)`	严格模式标志。	启用或停用对不支持的兼容行为的显式失败。	`static`	预期无。	在迁移审计期间保持启用。
`TCPDF::isStrictMode()`	无。	返回当前的严格模式标志。	`bool`	预期无。	在测试断言中很有用。
`TCPDF` 旧版方法	根据方法而定。	支持的方法会映射到核心文档调用；不支持的方法会明确失败。	根据方法而定。	`TcpdfNotImplementedException` 或 `UnsupportedFeatureException`。	在依赖某个方法之前，先查方法涵盖表。
`CompatAdapterInterface::getDocument()`	无。	由 `TCPDF` 实现的契约方法。	`Document`	预期无。	让工具能够访问原生文档。
`CompatAdapterInterface::Output(string $name = '', string $dest = '')`	文件名与旧版目的地。	委派给输出桥接。	`string`	核心写入错误或不支持的目的地错误。	镜像旧版 TCPDF 的输出入口；具体的 `TCPDF::Output` 提供 `'doc.pdf'`/`'I'` 的默认值。

旧版方法组

这张表是适配器所涵盖的 TCPDF 方法家族对照图。在到方法涵盖表查阅确切状态之前，先扫一遍这张表，快速判断某个旧版调用落在哪一类。

群组	代表性符号	默认行为	备注
生命周期与输出	`Open()`、`Close()`、`Output()`、`getPDFData()`	在原生文档之上保持 TCPDF 风格的文档生命周期。	迁移后请优先使用原生输出 API。
元数据	`SetTitle()`、`SetAuthor()`、`SetSubject()`、`SetKeywords()`、`SetCreator()`	把元数据 setter 映射到底层文档。	请在应用程序代码中保留元数据规范化逻辑。
页面与定位	`AddPage()`、`setPage()`、`lastPage()`、`GetX()`、`SetXY()`	把旧版单位与坐标转换为原生页面操作。	迁移后请以视觉方式验证绝对定位。
边距与版式	`SetMargins()`、`SetAutoPageBreak()`、`setCellPaddings()`、`getMargins()`	存储兼容性状态并映射支持的数值。	复杂的 TCPDF 分页行为可能需要人工检查。
字体与文本	`SetFont()`、`AddFont()`、`Cell()`、`MultiCell()`、`Write()`、`Text()`	把常见的文本操作路由到原生字体与文本 API。	请使用生产环境字体检查 CJK 与编码行为。
HTML	`writeHTML()`、`writeHTMLCell()`、`fixHTMLCode()`	把支持的 HTML 送入原生 HTML 流水线。	原生 renderer（渲染器）并不是 TCPDF HTML 的完整复刻。
图像与绘图	`Image()`、`Line()`、`Rect()`、`Circle()`、`SetDrawColor()`	通过适配器层映射支持的图形操作。	不支持的向量或特殊格式会明确失败。
导航与注解	`Bookmark()`、`AddLink()`、`SetLink()`、`Annotation()`	在存在映射的地方保留常见导航调用。	请验证生成的大纲与链接。
安全性与签名	`SetProtection()`、`setSignature()`、`setTimeStamp()`、`setUserRights()`	把支持的旧版安全调用桥接到原生功能。	请把密码学输出作为独立验证关卡。
表单、模板与变换	`TextField()`、`startTemplate()`、`StartTransform()`、`Rotate()`、`Scale()`	实现受支持的子集，并对不支持的行为明确失败。	发布前请对照方法涵盖表审计每一个调用。

Bootstrap 与配置

当你把适配器接入应用程序的启动路径时——注册全局别名，并在旧版常量与现代 AdaptationConfig 之间做选择——请查这张表。

符号	参数	默认行为	返回	抛出或失败条件	备注
`LegacyBootstrap::enableAliases()`	无。	注册一次兼容性别名。	`void`	自动加载或环境错误。	仅当旧版代码预期 TCPDF 名称必须存在于全局命名空间时才使用。
`LegacyBootstrap::isRegistered()`	无。	报告别名是否已注册。	`bool`	预期无。	在 bootstrap 测试中很有用。
`LegacyBootstrap::resetForTesting()`	无。	清除测试用注册状态。	`void`	预期无。	仅供测试的辅助方法。
`AdaptationConfig`	适配器标志与迁移控制项。	省略时使用包默认值。	`AdaptationConfig`	无效的选项值。	迁移审计期间请保持配置明确。
`AdaptationConfig::fromLegacyConstants()`	无。	读取已知旧版常量并构造配置。	`AdaptationConfig`	无效的旧版常量值。	供大型旧版应用程序使用的过渡辅助方法。
`LegacyDefaults`	无。	提供默认的旧版数值。	默认值集合。	预期无。	集中存放兼容性默认值。

桥接与辅助类

这些是适配器使用的内部转换类。主要在你贡献适配器涵盖范围，或诊断某个旧版参数如何被转换时查阅；日常应用程序代码不应直接使用。

符号	参数	默认行为	返回	抛出或失败条件	备注
`ConstructorBridge`	旧版构造函数参数清单。	把旧版选项规范化为 NextPDF 配置。	构造函数数据。	无效的旧版参数值。	由适配器内部使用。
`CellParameterAdapter`	TCPDF 单元格参数。	把旧版的位置参数映射到核心文本版式选项。	已适配的参数。	无效的尺寸或对齐方式。	在新代码中请优先使用原生核心方法。
`OutputBridge::dispatch(Document $document, string $filename, string $dest)`	原生文档、文件名与旧版目的地。	把 inline/download/存储行为映射到 NextPDF 输出 API。	`string`	核心写入错误；不支持的目的地。	输出前请验证文件名与存储根目录。
`OutputBridge::resolveDestination(string $dest)`	旧版目的地代码。	把目的地转换为原生输出目的地。	`OutputDestination`	不支持的目的地错误。	让目的地映射保持集中。
`ColorTranslator`	TCPDF 颜色参数。	把旧版颜色形式规范化。	核心颜色值。	无效的颜色值。	由颜色与绘图层使用。
`PageFormatResolver`	旧版页面格式输入。	把已知名称映射到核心页面尺寸。	页面格式值。	未知格式。	迁移后请使用明确的原生页面尺寸。
`UnitConverter`	旧版测量值与单位。	转换为核心单位。	数值。	无效的单位。	帮助保留旧版的版式行为。

异常

当某个迁移调用明确失败时，请查这张表。它会告诉你哪个异常代表「未实现」、哪个代表「已知但不支持」，以及各自如何恢复。

符号	含意	复原
`TcpdfNotImplementedException`	适配器有意不实现所请求的旧版方法。	改用原生 NextPDF API，或移除此依赖项。
`TcpdfNotImplementedException::forSilentIgnore()`	某个旧版调用此前会被忽略，但现在为了迁移清晰度而将其暴露出来。	判断明确的 no-op 行为是否可接受。
`TcpdfNotImplementedException::forUnimplemented()`	某个旧版调用没有已实现的适配器路径。	改写这个调用，或将其隔离在迁移代码后面。
`UnsupportedFeatureException`	这个旧版功能是已知的，但在适配器边界内并不支持。	查阅迁移指南，并将该功能隔离在应用程序适配器后面。
`UnsupportedFeatureException::forMethod()`	创建一个特定于方法的不支持功能错误。	在兼容性贡献中使用，以保持一致的失败消息。

开发备注

请把适配器视为迁移工具。新代码应直接面向核心 NextPDF API。
不支持的行为应当明确失败。除非应用程序明确接受这个风险，否则不要捕获兼容性异常后继续产出一份不完整的文档。
请让迁移变更保持小幅，并对照方法涵盖表验证每一个旧版方法。