compat-legacy 快速入门

概览

本页将带你从已安装的软件包开始，生成一份完整的 PDF，然后运行迁移前需要执行的严格模式审计。每个代码块都对应软件包测试套件断言的一项行为，因此这里展示的输出就是测试会检查的内容。

开始之前

请按照 /integrations/tcpdf-compat/install/ 安装软件包并确认引擎链接。你需要 PHP 8.4，并且依赖解析必须能解析 nextpdf/core ^3.0。

1. 制作你的第一份文档

只需更改 import，并保留原有 TCPDF 风格的调用。这正是 tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php 所断言的确切接口。

examples/quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

运行它：

php examples/quickstart-first.php

生成的文件 quickstart.pdf 是有效的 PDF 2.0。测试套件断言：对于 S、F 与 E 目标以及 getPDFData()，等效的字符串输出都以 %PDF 开头。

输出目标

Output($name, $dest) 会通过安全的输出桥接器来映射 TCPDF 的目标代码。以下是测试套件所覆盖的行为：

$dest	行为	返回值
'S'	以字符串形式返回 PDF	PDF 字节（%PDF…）
'F'	将 PDF 写入指定路径	空字符串
'E'	返回 base64 MIME 主体	一个 Content-Type: application/pdf 块
'I'	内联显示（默认）	取决于输出桥接器
'D'	下载	取决于输出桥接器

与传统 TCPDF 不同，Output() 不会直接输出到当前活动的输出缓冲区，因此你可以安全地在队列工作进程中，或在自行掌控响应的 HTTP 处理程序中调用它。请参阅 /integrations/tcpdf-compat/production-usage/。

2. 无需修改即可运行既有的 TCPDF 代码

在实际迁移中，你通常会先只更改 import 或别名，然后运行既有代码。如果你的代码库通过全局命名空间调用 new \TCPDF(...)，请在启动时启用一次可选加入的别名（详见 /integrations/tcpdf-compat/boot-and-discovery/）：

examples/quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

LegacyBootstrap::enableAliases() 是幂等的。只有在这些类不存在时，它才会注册 \TCPDF、\TCPDF_STATIC、\TCPDF_FONTS、\TCPDF_COLORS 与 \TCPDF_IMAGES。软件包测试 tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php 断言：这些别名会注册、此调用具备幂等性，并且 new \TCPDF() 是该适配器的实例。如果同一个进程中已加载真正的 TCPDF 库，请勿启用别名；请参阅 /integrations/tcpdf-compat/troubleshooting/。

3. 以严格模式审计

这个步骤是安全迁移的关键。严格模式关闭（默认）时，无法重现 TCPDF 行为的方法会静默降级。严格模式开启时，这些方法会抛出 TcpdfNotImplementedException，并附带被忽略参数的确切清单。请在专门的审计流程中运行这项操作，切勿在生产环境中运行。

examples/quickstart-strict-audit.php

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

软件包测试 tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php 断言：这个确切的调用在严格模式下会抛出异常、在默认模式下保持静默，且异常消息中包含方法名称与被忽略的参数。请将收集到的异常当作你的迁移工作清单；请参阅 /integrations/tcpdf-compat/migration/。

4. 在需要时触及现代 API

每个适配器实例都会公开其底层的引擎文档对象。你可以用它调用没有 TCPDF 对应项的现代 NextPDF 方法：

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() 会返回该适配器所包装的 NextPDF\Core\Document。这是推荐的退出路径：逐个将调用点迁移到现代 API，直到你能移除适配器为止。

一开始就应预期的行为差异

• MultiCell() 返回 1，而非已渲染的单元格数量。基于 MultiCell() 返回值进行分支的代码需要调整。
• Error() 会抛出 RuntimeException，而非调用 die()。原本依赖进程终止的代码必须改为捕获该异常。
• 具体的 PDF 字节与 TCPDF 的输出不同。请为字节级测试断言重新建立基准，改为针对已渲染的内容进行断言。

完整的逐方法清单位于 /integrations/tcpdf-compat/method-coverage/。

后续步骤

• /integrations/tcpdf-compat/migration/ — 完整的逐文件迁移策略。
• /integrations/tcpdf-compat/configuration/ — 严格模式、默认值以及现代的配置对象。
• /integrations/tcpdf-compat/production-usage/ — 工作进程、输出缓冲区与性能。
• /integrations/tcpdf-compat/security-and-operations/ — 加密与签名的态势。

另请参阅

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — 输出行为的权威来源（oracle）
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — 严格模式的权威来源（oracle）
• docs/TCPDF_COVERAGE.md — 权威的覆盖率对照表