NextPDF compat-legacy 集成指南

概览

本页说明如何将 nextpdf/compat-legacy 接入应用，让既有 TCPDF 6.x 代码在 NextPDF 引擎上运行。本软件包是迁移辅助工具，并非永久垫片，目标是在采用现代 API 后将其移除（请参阅 /integrations/tcpdf-compat/migration/）。它是与 TCPDF 兼容的替代方案，而不是可直接替换的复制品：在约 120 个已调查的 TCPDF 方法中，有 94 个会直接委托。其余方法存在已记录的行为差异（请参阅 /integrations/tcpdf-compat/method-coverage/）。

安装

composer require nextpdf/compat-legacy:^3.0

这会通过传递依赖解析出 nextpdf/core ^3.0。完整需求和验证检查见：/integrations/tcpdf-compat/install/.

启动与自动发现

自动加载阶段不会执行任何全局接线。引入本软件包不会创建全局 \TCPDF。调用方如何解析这个类由你决定：

建议做法（显式导入）。 将每个文件中的 use/require 行改为 use NextPDF\Compat\Tcpdf\TCPDF;。这样明确无歧义，也便于用 grep 搜索。
选择性启用的全局别名。 在启动阶段调用一次 LegacyBootstrap::enableAliases()，即可注册 \TCPDF 和四个辅助类，但前提是这些名称尚未被占用。有关机制、幂等性以及与真实 TCPDF 的冲突规则，请参阅：/integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

容器绑定

本软件包不附带任何框架的 service provider 或 bundle。集成层由你自行掌控，只是一层薄包装。请绑定一个工厂，让它为每份文档返回全新的 adapter；不要使用共享单例，因为文档状态在各实例之间彼此独立（请参阅 /integrations/tcpdf-compat/production-usage/ § Concurrency）。

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

在 Symfony 中，请将该工厂注册为非共享（non-shared）服务。在 Laravel 中，请使用 bind（而非 singleton）进行绑定，确保每次解析都得到一个新实例。软件包本身保持与框架无关。

发布配置

没有可发布的框架配置文件。请通过旧版 K_* / PDF_* 常量进行配置（在你的 bootstrap 中、首次构造之前定义它们），或使用现代的不可变 NextPDF\Compat\Tcpdf\Config\AdaptationConfig 对象。请参阅 /integrations/tcpdf-compat/configuration/.

Service-provider/bundle 冒烟测试

完成接线后，请验证该集成能够生成有效 PDF。这对应 tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php 断言的接口：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

在 HTTP 或 worker 上下文中，请使用 Output(..., 'F') 或 'S'。不要依赖内联（inline）路径。完整运维指引请见 /integrations/tcpdf-compat/production-usage/.

公开 API 入口点

入口点	用途
`NextPDF\Compat\Tcpdf\TCPDF`	与 TCPDF 兼容的 facade。每份文档都应单独构造一个。
`TCPDF::getDocument()`	返回所包装的 `NextPDF\Core\Document`，作为进入现代 API 的逃生出口。
`TCPDF::setStrictMode(bool)`	迁移审计开关（请参阅 /integrations/tcpdf-compat/configuration/）。
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	可选启用的全局类别名。
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	现代的不可变配置对象。
`NextPDF\Compat\Contracts\CompatAdapterInterface`	共享的兼容性契约（compat contract）。

TCPDF API 覆盖范围

仓库内的 docs/TCPDF_COVERAGE.md 是权威且经过测试验证的覆盖矩阵。面向读者的摘要，包括镜像、静默忽略、未实现以及不适用的方法，见 /integrations/tcpdf-compat/method-coverage/. 本软件包并不声称「可直接替换」或「100% 兼容」。更准确的描述是：它是一个与 TCPDF 兼容的替代方案，提供已知且经测试的接口，并记录了行为差异。

另请参阅

docs/TCPDF_COVERAGE.md —— 权威覆盖范围来源（仓库内）
/integrations/tcpdf-compat/boot-and-discovery/ —— facade 的暴露方式与别名机制
/integrations/tcpdf-compat/method-coverage/ —— 各方法的行为与差异
/integrations/tcpdf-compat/migration/ —— 分阶段的迁移策略
/integrations/tcpdf-compat/production-usage/ —— 在负载场景下运行 adapter
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php —— 输出行为的标准依据（oracle）