配置 compat-legacy

概览

此适配器提供三个配置入口：

严格模式 — 一个审计开关，会把静默丢失的参数转为抛出异常。默认关闭。
旧版常量 — TCPDF 的 K_* / PDF_* 常量，会以 6.2.13 的默认值自动定义，让读取它们的旧版代码可以正常运行。
AdaptationConfig — 一个现代、不可变的配置对象，用于取代基于常量的配置。

你主要通过已经在调用的同一组 TCPDF 方法来配置文档（SetMargins()、SetFont() 等等）。下面这些接口涵盖的是兼容层特有的部分。

严格模式

严格模式是迁移时最重要的配置项。它不会改变渲染输出。它控制的是：当某次调用无法复现 TCPDF 行为时，是要明确报错，还是静默降级。

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();

$pdf->setStrictMode(true);   // audit: throw on silent parameter loss
$isOn = $pdf->isStrictMode(); // true
$pdf->setStrictMode(false);  // back to backward-compatible default

其行为由 tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php 断言如下：

模式	调用了会静默忽略的方法	结果
关闭（默认）	例如带有额外参数的 `Image()`	照常执行；被忽略的参数不会产生任何作用
开启	相同的调用	抛出 `TcpdfNotImplementedException`，并指出被忽略的参数
开启	仅使用受支持的参数调用某个会静默忽略参数的方法	不会抛出（例如 `SetProtection([], 'u', 'o', 0, [])`）

严格模式是叠加性的。当某个方法确实支持某个参数时，仍会照常委托执行；严格模式只是针对被丢弃的参数额外加上一道异常防护。建议只在专用 CI 任务或一次性审计流程中使用，而不是用于生产环境。这一结论遵循 OWASP ASVS 5.0 错误处理的明确失败原则（其 reference_id 条款记录在 RAG 附带文件中）：调用方必须能够察觉其意图何时未被遵循。

请勿在开启严格模式的情况下发布生产环境代码。被静默忽略的参数属于开发体验问题，而非运行时故障；在生产环境渲染路径中抛出异常，比降级后的输出更糟。请审计、修正，然后关闭它 — 参见 /integrations/tcpdf-compat/migration/.

旧版 TCPDF 常量

旧版 TCPDF 会从 K_* 与 PDF_* 常量读取配置。此适配器在构造时只会在它们尚未被定义时自动定义它们，并使用 TCPDF 6.2.13 的默认值。如果你的应用程序已经定义了某个常量（例如自定义的 K_PATH_FONTS），你的值会被保留。

部分默认值（完整清单：src/Compat/Tcpdf/Config/LegacyDefaults.php）：

常量	默认值	备注
`PDF_PAGE_FORMAT`	`A4`
`PDF_PAGE_ORIENTATION`	`P`
`PDF_UNIT`	`mm`
`PDF_MARGIN_LEFT` / `RIGHT`	`15`	用户单位
`PDF_MARGIN_TOP`	`27`	用户单位
`PDF_MARGIN_BOTTOM`	`25`	用户单位
`PDF_FONT_NAME_MAIN`	`helvetica`
`PDF_FONT_SIZE_MAIN`	`10`
`K_CELL_HEIGHT_RATIO`	`1.25`
`K_TCPDF_CALLS_IN_HTML`	`false`	已加固 — 永远为 false；标记无法触发 PHP 执行
`K_TCPDF_THROW_EXCEPTION_ERROR`	`true`	已加固 — `Error()` 永远会抛出；绝不会 `die()`
`K_TIMEZONE`	`UTC`

其中两个是出于安全考虑而刻意固定的，且无法通过配置放宽：K_TCPDF_CALLS_IN_HTML 永远为 false，而 K_TCPDF_THROW_EXCEPTION_ERROR 实际上永远为 true。如果旧版代码依赖这两种不安全旧版行为中的任意一种，就必须变更该代码 — 参见 /integrations/tcpdf-compat/security-and-operations/.

如果要定义你自己的常量，请在第一次构造适配器之前定义它们（通常是在你的应用程序启动代码中）：

<?php

declare(strict_types=1);

// Define BEFORE constructing the adapter; the adapter will not override it.
define('PDF_CREATOR', 'My Application');
define('PDF_AUTHOR', 'My Application');

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
// Creator and Author are seeded from your constants.

现代的 AdaptationConfig 对象

对于不想依赖全局常量的代码，此包提供了一个不可变的配置值对象 NextPDF\Compat\Tcpdf\Config\AdaptationConfig。它是 final readonly 的，且每个字段的默认值都是 TCPDF 6.2.13 的值。你可以安全地只传入你想变更的字段来构造它。

你也可以根据当前已定义的任何旧版常量来构造它：

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Config\AdaptationConfig;

// Snapshot the currently-defined legacy constants into an object:
$config = AdaptationConfig::fromLegacyConstants();

echo $config->pageFormat;   // 'A4' unless a constant overrides it
echo $config->fontNameMain; // 'helvetica'
echo $config->marginLeft;   // 15.0

AdaptationConfig 是配置的迁移目标。当你把各个调用点迁移到现代 API 上时，请用明确的 AdaptationConfig 字段取代常量查找。这样配置就是类型化且局部的，而非全局的。

配置解析顺序

当适配器构造文档时，配置会按以下顺序解析（后面的步骤不会覆盖前面的步骤）：

构造函数参数（orientation、unit、format、…）— 对于它们所涵盖的值具有最高优先级。
预先存在、由应用程序定义的旧版常量。
TCPDF 6.2.13 默认常量，由 LegacyDefaults 为任何尚未定义的常量自动定义。

构造函数参数 unicode、encoding 与 diskcache 会为了签名兼容性而被接受，但不会产生任何作用。NextPDF 始终是 Unicode 且 UTF-8，并且没有磁盘上的页面缓存。pdfa 构造函数标志也会被接受，但 PDF/A 归档一致性需要商业版（参见 /integrations/tcpdf-compat/security-and-operations/）。

另请参阅

src/Compat/Tcpdf/Config/LegacyDefaults.php — 权威常量默认值
src/Compat/Tcpdf/Config/AdaptationConfig.php — 现代的配置对象
/integrations/tcpdf-compat/migration/ — 将配置迁出全局常量
/integrations/tcpdf-compat/security-and-operations/ — 两个已加固、不可配置的标志