compat-legacy クイックスタート

概要

このページでは、インストール済みのパッケージを使って完成した PDF を作成する手順から、移行前に実行する厳格モード監査までを順に案内します。すべてのコードブロックは、パッケージのテストスイートが検証する挙動を反映しているため、ここで示す出力はテストで確認済みの内容そのものです。

始める前に

パッケージをインストールし、/integrations/tcpdf-compat/install/. に従ってエンジンのリンクを確認してください。PHP 8.4 が必要で、nextpdf/core ^3.0 が解決されている必要があります。

1. 最初のドキュメントを作成する

インポートを変更し、TCPDF スタイルの呼び出しはそのままにします。これは 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->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 コードを変更せずに実行する

実際の移行では、まずインポートまたはエイリアスのみを変更して既存のコードを実行します。コードベースがグローバル名前空間に対して new \TCPDF(...) を呼び出している場合は、起動時に一度だけ、オプトインのエイリアスを有効化してください（/integrations/tcpdf-compat/boot-and-discovery/ で解説しています）：

<?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 をスローします。これは専用の監査パスで実行し、本番環境では決して実行しないでください。

<?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 メソッドを呼び出します：

<?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() は die() を呼び出す代わりに RuntimeException をスローします。プロセスの終了に依存していたコードは、例外をキャッチする必要があります。
正確な 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/ — 暗号化と署名に関する方針。