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）