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/. を参照してください。

ブートと自動検出

オートロード時にグローバルな組み込みは行われません。パッケージを require しても、グローバルな \TCPDF は作成されません。呼び出し側でクラスをどのように解決するかは、利用者が選択します。

推奨（明示的なインポート）。 ファイルごとに use/require 行を use NextPDF\Compat\Tcpdf\TCPDF; に変更します。あいまいさがなくなり、grep でも検索しやすくなります。
オプトインのグローバルエイリアス。 ブート時に LegacyBootstrap::enableAliases() を一度呼び出すと、\TCPDF と 4 つのヘルパークラスが登録されます。ただし、それらの名前がまだ使用されていない場合に限ります。仕組み、冪等性、本物の 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();

コンテナのバインディング

このパッケージには、フレームワーク向けのサービスプロバイダーやバンドルは同梱されていません。統合は、利用者自身が管理する薄いレイヤーです。ドキュメントごとに新しいアダプターを返す ファクトリ をバインドしてください。共有シングルトンにはしないでください。ドキュメントの状態はインスタンスごとに保持されるためです（/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 では、このファクトリを非共有サービスとして登録します。Laravel では、各解決で新しいインスタンスが作成されるように、bind（singleton ではなく）でバインドします。パッケージ自体はフレームワーク非依存のままです。

設定の公開

公開可能なフレームワーク設定ファイルはありません。設定は、レガシーな K_* / PDF_* 定数（最初の構築前にブートストラップで定義します）か、モダンでイミュータブルな NextPDF\Compat\Tcpdf\Config\AdaptationConfig オブジェクトを通じて行います。/integrations/tcpdf-compat/configuration/. を参照してください。

サービスプロバイダー/バンドルのスモークテスト

組み込み後は、統合によって有効な 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 またはワーカーのコンテキストでは、Output(..., 'F') または 'S' を使用してください。インライン出力に頼らないでください。運用に関する詳しいガイダンスは、/integrations/tcpdf-compat/production-usage/. にあります。

公開 API のエントリーポイント

エントリーポイント	用途
`NextPDF\Compat\Tcpdf\TCPDF`	TCPDF 互換ファサード。ドキュメントごとに構築。
`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`	共有の互換コントラクト。

TCPDF API のカバレッジ

テストで検証済みの正式なカバレッジマトリクスは、リポジトリ内のファイル docs/TCPDF_COVERAGE.md です。読者向けの要約（ミラーリング済み、サイレント無視、未実装、該当なしのメソッド）は、/integrations/tcpdf-compat/method-coverage/. にあります。「そのまま差し替え可能」や「100% 互換」といった主張は一切していません。正確には、既知かつテスト済みの範囲と、ドキュメント化された動作上の違いを持つ、TCPDF 互換の代替実装です。