設定 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/ — 兩個已強化且不可組態的旗標