安装 NextPDF compat-legacy

概览

nextpdf/compat-legacy 是一个 Composer 库。它需要 PHP 8.4 或更新版本，以及 nextpdf/core ^3.0。安装它并不会更改你既有的 TCPDF 调用——它新增了一个你可以切换过去使用的类。

需求

依赖包	版本	单一可信来源
PHP	`>=8.4 <9.0`	包 `composer.jsonrequire.php`
`nextpdf/core`	`^3.0`	包 `composer.jsonrequire`
Composer	2.7 或更新版本	工具链基线

此包声明达到 PHPStan Level 10 且不使用 baseline，并附带独立测试套件。它在运行时需要 PHP 8.4。更广泛的 NextPDF 引擎通过 backport 系列支持 PHP 8.1 至 8.4，但此适配器将 PHP 8.4 设为最低版本。

安装

使用 Composer 添加此包：

composer require nextpdf/compat-legacy:^3.0

Composer 会将 nextpdf/core ^3.0 解析为传递依赖。核心功能集不需要额外的运行时扩展。

此包的元数据也会通过 Composer 的 replace 项响应历史名称 nextpdf/compat-tcpdf。新的安装应改为要求 nextpdf/compat-legacy，这是规范的包名称。

验证安装

安装后，确认适配器类可以加载，且引擎链接可以解析。以下检查会完全在内存中生成一份单页 PDF，并验证 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, 'compat-legacy install verified');

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

if (! str_starts_with($bytes, '%PDF')) {
    fwrite(STDERR, "Install check failed: output is not a PDF.\n");
    exit(1);
}

echo "OK: adapter loaded, engine linked, PDF produced (" . strlen($bytes) . " bytes).\n";

运行它：

php examples/install-verify.php

预期输出是单独一行 OK:。返回字符串以 %PDF 前缀开头，即确认适配器已构建出 NextPDF\Core\Document，委派了页面与文本调用，并序列化出有效的 PDF 2.0 输出。

验证引擎版本

此适配器需要 nextpdf/core ^3.0。确认解析后的版本：

composer show nextpdf/core --format=json

若 Composer 解析出的核心版本不在 ^3.0 范围内，此适配器会在构建时快速失败，而非生成错误输出。若你的项目也直接依赖该引擎，请在你的 composer.json 中明确锁定引擎版本。

可选：全局类别名

若你的代码库通过全局命名空间调用 new \TCPDF(...)，而你尚无法更改那些 use/require 行，此包可以注册全局别名。该功能需要选择性启用，并在 /integrations/tcpdf-compat/boot-and-discovery/. 中说明。若同一进程中也安装了真正的 TCPDF 库，请勿启用它；冲突避免规则请参见 /integrations/tcpdf-compat/troubleshooting/。

安装不会做什么

它不会修改或移除既有的 TCPDF 依赖包。移除 tecnickcom/tcpdf 是 /integrations/tcpdf-compat/migration/. 中有意安排的后续步骤。
它不会启用数字签名或 PDF/A。这些功能需要商业版的 NextPDF 版本（参见 /integrations/tcpdf-compat/security-and-operations/）。
它不会更改 PDF 输出目标。输出始终为 PDF 2.0。

后续步骤

/integrations/tcpdf-compat/quickstart/ — 创建你的第一份真实文档。
/integrations/tcpdf-compat/configuration/ — 严格模式与适配器配置。
/integrations/tcpdf-compat/migration/ — 逐文件迁移策略。
/integrations/tcpdf-compat/method-coverage/ — 每个 TCPDF 方法在这里的实际行为。

另请参阅

包 composer.json — 权威的依赖约束
docs/TCPDF_COVERAGE.md — 权威的覆盖矩阵（位于 repo 内）