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 — 權威的涵蓋率對照表