TCPDFからの移行

このガイドでは、レガシーTCPDF（tecnickcom/tcpdf）からTCPDF-Nextへの既存プロジェクトの移行手順を説明します。TCPDF-Nextは完全な書き直しであり、ドロップイン代替ではありませんが、移行プロセスは体系的で明確に定義されています。

主な違い

機能	TCPDF（レガシー）	TCPDF-Next
PHPバージョン	5.3+	8.5+
PDFバージョン	PDF 1.7	PDF 2.0
アーキテクチャ	単一のモノリシッククラス（約27,000行）	17のモジュール名前空間、142クラス
APIスタイル	手続き的、PascalCaseメソッド	フルエントビルダー、camelCaseメソッド
型安全性	型なし	`declare(strict_types=1)`、enum、readonly
静的解析	なし	PHPStanレベル8、エラーゼロ
暗号化	RC4、AES-128、AES-256	AES-256のみ（PDF 2.0リビジョン6）
署名	基本的なPKCS#7	PAdES B-BからB-LTA
PDF/A	PDF/A-1b（部分的）	PDF/A-4（完全なISO 19005-4）
クロスリファレンス	レガシーxrefテーブル	クロスリファレンスストリーム
フォント処理	独自バイナリ形式	標準TTF/OTF、自動サブセット化
HTML解析	正規表現ベース（制限付き）	DOMベースエンジン（改善されたCSSサポート）
依存関係	ゼロ	ゼロ

APIマッピング：旧メソッドから新メソッド

最も目に見える変更はAPI面です。TCPDF-NextはcamelCase、名前付きパラメータ、値オブジェクト、フルエントビルダーを使用します：

レガシーTCPDF	TCPDF-Next	備考
`new TCPDF()`	`Document::create()`	フルエントビルダー、名前付きパラメータ
`$pdf->Cell()`	`$pdf->cell()`	camelCase
`$pdf->MultiCell()`	`$pdf->multiCell()`	camelCase
`$pdf->SetFont()`	`$pdf->setFont()`	camelCase
`$pdf->SetDrawColor()`	`$pdf->setDrawColor()`	camelCase
`$pdf->Output('file.pdf', 'F')`	`$pdf->save('file.pdf')`	明示的メソッド
`$pdf->Output('file.pdf', 'I')`	`$pdf->output('file.pdf', OutputDestination::Inline)`	Enumベース

ドキュメント作成

TCPDF（変更前）：

php

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);
$pdf->SetCreator('My App');
$pdf->SetAuthor('John Doe');
$pdf->SetTitle('Invoice #12345');
$pdf->SetKeywords('invoice, payment, monthly');
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->SetMargins(15, 15, 15);
$pdf->SetAutoPageBreak(true, 15);
$pdf->AddPage();

TCPDF-Next（変更後）：

php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Orientation;
use YeeeFang\TcpdfNext\Document\Margins;

$pdf = PdfDocument::create()
    ->setCreator('My App')
    ->setAuthor('John Doe')
    ->setTitle('Invoice #12345')
    ->setKeywords(['invoice', 'payment', 'monthly'])
    ->setPageFormat(PageFormat::A4)
    ->setOrientation(Orientation::PORTRAIT)
    ->setMargins(Margins::uniform(15))
    ->setAutoPageBreak(true, bottomMargin: 15)
    ->build();

$page = $pdf->addPage();

設定変更：定数からEnumへ

レガシーTCPDFは整数定数とマジック文字列を使用していました。TCPDF-NextはPHP 8.1+のenumを使用します：

php

// TCPDF：暗号化モード用のマジック整数
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3);

// TCPDF-Next：型安全なenum
$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256)
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY)
    ->setUserPassword('user')
    ->setOwnerPassword('owner')
    ->apply();

カラー処理：配列からColor値オブジェクトへ

php

// TCPDF：素の整数配列
$pdf->SetDrawColor(255, 0, 0);
$pdf->SetFillColor(0, 128, 255);

// TCPDF-Next：Color値オブジェクト
use YeeeFang\TcpdfNext\Color\Color;

$canvas->setStrokeColor(Color::rgb(255, 0, 0));
$canvas->setFillColor(Color::rgb(0, 128, 255));
$canvas->setFillColor(Color::hex('#0080FF'));
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0));

ページサイズ：文字列からPageSize値オブジェクトへ

php

// TCPDF：マジック文字列
$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage('L', 'LETTER');

// TCPDF-Next：型安全なenumと値オブジェクト
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Orientation;

$pdf = PdfDocument::create()
    ->setPageFormat(PageFormat::A4)
    ->build();

$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE);
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

暗号化：RC4/AES-128からAES-256のみへ

TCPDF-Nextはすべてのレガシー暗号化アルゴリズムを削除しています。アプリケーションがRC4またはAES-128暗号化を使用している場合、AES-256にアップグレードする必要があります：

php

// TCPDF：複数のアルゴリズム（安全でないものを含む）
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- 安全でない
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- 安全でない
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next：AES-256のみ（唯一の安全なオプション）
$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256) // 唯一のオプション
    ->setUserPassword('user')
    ->setOwnerPassword('owner')
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY)
    ->apply();

WARNING

レガシーTCPDFでRC4またはAES-128で暗号化されたPDFは、AES-256で再暗号化する必要があります。RC4暗号化は実質的なセキュリティを提供しません -- 数秒で破るツールが存在します。

破壊的変更チェックリスト

移行を開始する前にこのチェックリストを確認してください：

[ ] PHP 8.5+が必要 -- PHPランタイムをアップグレードしてください。PHP 7.xおよび8.0-8.4はサポートされていません。
[ ] 名前空間の変更 -- TCPDFクラス参照をYeeeFang\TcpdfNext\...名前空間に置き換えてください。
[ ] camelCaseメソッド -- SetFont()はsetFont()に、MultiCell()はmultiCell()に、など。
[ ] コンストラクタの置き換え -- new TCPDF(...)はPdfDocument::create()->...->build()になります。
[ ] Outputメソッドの置き換え -- Output('file.pdf', 'F')はsave('file.pdf')になります。
[ ] フォント形式の変更 -- TCPDFバイナリフォントファイル（.php + .z）をオリジナルのTTF/OTFファイルに置き換えてください。
[ ] ヘッダー/フッターメソッド -- クラス継承（extends TCPDF）をイベントコールバック（onPageHeader()）に置き換えてください。
[ ] 暗号化のアップグレード -- RC4とAES-128は削除されました。AES-256に移行してください。
[ ] カラー配列 -- 素の[255, 0, 0]配列をColor::rgb(255, 0, 0)に置き換えてください。
[ ] 文字列ページサイズ -- 'A4'文字列をPageFormat::A4 enum値に置き換えてください。
[ ] キーワード形式 -- カンマ区切り文字列を配列に変更：'a, b'は['a', 'b']になります。
[ ] ユニットパラメータの削除 -- TCPDF-Nextはデフォルトでミリメートルを使用します（ドキュメントごとに設定可能）。
[ ] 戻り値の型 -- 多くのメソッドがvoidの代わりに型付き結果を返すようになりました。#[\NoDiscard]の戻り値を使用してください。

互換性レイヤー（段階的移行）

大規模なコードベースのために、TCPDF-Nextはほとんどのレガシーメソッド呼び出しをマッピングする互換性レイヤーを提供しています：

php

// インポートを置き換えてください -- 既存のコードはそのまま動作します
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

互換性レイヤーはTCPDFのパブリックAPIの約80%をカバーしています。サポートされていないメソッドは、最新の代替手段のガイダンス付きでDeprecatedMethodExceptionをスローします。

WARNING

互換性レイヤーは移行支援ツールであり、永続的なソリューションではありません。オーバーヘッドが追加され、TCPDF-Nextの高度な機能（PAdES署名、PDF/A-4、クロスリファレンスストリーム）は公開されません。ネイティブAPIへの移行を完了する計画を立ててください。

完全なAPIマッピング

30以上のメソッドをカバーする包括的なメソッド対応表については、APIマッピングテーブルをご覧ください。

さらに詳しく

APIマッピングテーブル -- 完全なメソッド対応表
セキュリティ概要 -- 移行で対処されるCVE修正
APIリファレンス -- TCPDF-Next完全APIドキュメント
FAQ -- 一般的な移行の質問

TCPDFからの移行 ​

主な違い ​

APIマッピング：旧メソッドから新メソッド ​

ドキュメント作成 ​

設定変更：定数からEnumへ ​

カラー処理：配列からColor値オブジェクトへ ​

ページサイズ：文字列からPageSize値オブジェクトへ ​

暗号化：RC4/AES-128からAES-256のみへ ​

破壊的変更チェックリスト ​

互換性レイヤー（段階的移行） ​

完全なAPIマッピング ​

さらに詳しく ​