レガシーからの移行：TCPDF、FPDF、そしてその仲間たち

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

概要

あなたの PDF が TCPDF、FPDF、mPDF、dompdf で生成されているなら、そのコードはおそらくまだ動いています。だからこそ、トラブルが見過ごされやすいのです。ライブラリは動き、ファイルは開き、ギャップが表に出るのは、誰かが署名済み・アーカイブ可能・アクセシブルな文書を求めてきて、答えが「ここからはできません」になる日だけです。

このページは移行のストーリーです。その壁とは何か、なぜそれが偶発的ではなく構造的なものなのか、そして NextPDF がそこから抜け出す段階的な道筋 — バイト単位で同一なドロップイン代替の約束ではなく、移行を助けるための TCPDF 互換サーフェスを含む — をどう提供するかを説明します。

なぜこれが重要か

PDF ライブラリは、一度だけ呼び出すレンダリングの呼び出しではありません。それは、あなたの文書が存在し続ける限り受け継ぐ依存関係です。その依存関係が動きを止めると、文書は新しいことができなくなります。そしてあなたがそれに気づくのは、最悪のタイミング、つまり顧客や監査人や規制当局が基準を突き付けてくる瞬間です。

壁はこのような形をしています。フォーマットは前へ進みました。PDF 2.0 は標準の現行版であり（SpecSpec: ISO 32000-2ISO 32000-2）、1.x 構造に留まったライターは、ツールチェーンの残りが前提とするフォーマットに後れを取っています。署名は薄いか後付けで、署名を成立させる PAdES ベースラインプロファイルには遠く及びません（SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4）。PDF/A ファミリーへのアーカイブ出力や、アクセシビリティのためのタグ付き構造は、欠けているか壊れやすいかのどちらかです。そして API そのものが型を持っていません。文字列で表す向き、位置で渡す真偽値、偶然に気づくデフォルト値 — コンパイラはあなたを助けられず、レビュアーも同様です。

これらはどれも、その場しのぎで直せるバグではありません。これらは、より古い時代のために作られたツールの形そのものであり、そうしたツールのいくつかは、いまやあなたの文書が満たさなければならない標準へ向けて積極的に動いてはいません。

要点

• レガシーの PHP PDF ライブラリは、たいていまだ 動きます。問題は、それらが 完全なモダン準拠で生成できないことが多いもの です。PDF 2.0、ベースライン準拠の署名、検証済みの PDF/A、タグ付きアクセシビリティ — 名前を挙げたライブラリ群におけるサポートは限定的か欠如しています。
• NextPDF は、デフォルトで PDF 2.0 を書き出す PHP 8.4 エンジンです。厳格な型、アーカイブプロファイル、そして PAdES 署名を第一級の出力として備えています。
• 初日にすべてを書き直す必要はありません。TCPDF 互換サーフェス によって、馴染みのある呼び出しが動き続ける一方で、重要な文書ロジックを移行できます。
• そのサーフェスは TCPDF と バイト単位で同一なのではなく、互換 です。それは移行を渡るための橋であり、振る舞いの違いは文書化されています — すべてのスクリプトが無変更で動くという主張ではありません。
• 誠実な判断基準は、新しい能力が移行に見合うかどうかです。あるワークロードにとっては見合いません。その場合、私たちははっきりそう述べます。

NextPDF のアプローチ

このアプローチは、移行を飛躍ではなく一連の手順にすることです。全行程を通じて文書を生成し続け、ビッグバン的な書き直しに一度のリリースを賭けるのではなく、古い制約を一つずつ手放していきます。

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 はベースラインであり、機能フラグではありません。 NextPDF はデフォルトでフォーマットの現行版を書き出し（SpecSpec: ISO 32000-2ISO 32000-2）、プロファイルが求める場合には古い構造もシリアライズできます。1.x 構造に凍結されたライブラリは、ここであなたと足並みを揃えられません。それは欠けている設定ではなく、そのライブラリが先んじて存在していた時代だからです。

アーカイブとアクセシビリティはライターの性質です。 バリデータが PDF/A として受け入れるファイルを生成することは、エンジンが書き込みの過程で行わなければならないことであり、あとからホチキス留めすることはできません（SpecSpec: ISO 19005-4ISO 19005-4）。PDF をアクセシブルにするタグ付き構造についても同じです。NextPDF はこれらを生成時に構築します。それはまさに、多くのレガシーツールが踏めない — あるいは部分的にしか踏めず、バリデータが受け入れる水準に届かない — ステップです。

署名はベースラインの基準を満たします。 PDF における高度電子署名は PAdES プロファイルに従い（SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4）、そこではダイジェストが宣言済みのバイト範囲をカバーし、署名はバリデータが確認するメタデータを携えます。後付けの署名ヘルパーがその基準に届くことはめったにありません。NextPDF はこれを後回しの作業ではなく、第一級の出力として扱います。

互換サーフェスは橋であり、それを誠実に述べます。 TCPDF 互換レイヤーが存在するのは、重要な部分を移行する間も、既存の呼び出し箇所が文書を生成し続けられるようにするためです。それはあらゆる NextPDF 移行ガイドと同じモデルに従います。すなわち、ソースライブラリと互換だが バイト単位で同一ではなく、振る舞いの違いは書き留めてあります。その誠実さこそが要点です — 暗黙のうちに「99% ドロップイン」と謳うのは、まさにこのエンジンが拒むよう作られている類の当て推量です。

Human-factors note:Human-factors note

The reason to migrate is rarely the code you have today; it is the document you will be asked for tomorrow. Maintainability is a named quality property — how readily a system can be analysed and changed as needs shift (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). A dependency that has stopped moving quietly erodes it, and you only feel the cost when a new requirement arrives and the answer has to be “not from here.” A staged move pays that cost on your schedule, while the documents keep flowing, instead of all at once under deadline.

実践例

移行の形は、呼び出し箇所では小さなものです。古いコードは互換サーフェスを通じてファイルを生成し続け、新しいコードは型付きのネイティブ API を通じて意図を明示し、レガシーライブラリが到達できない — あるいは限定的な準拠でしか到達できない — 出力を求めます。

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

最初のブロックは足がかりです。文書が流れ続けるために、アプリケーションの中で変える必要のあるものは何もありません。2 つ目は目的地です。「ポートレート」「文字列出力」そしてフォントが明示された型付きの呼び出しであり、アーカイブ、署名、アクセシビリティが、ぶつかる壁ではなく切り替えられる出力になります。

よくある誤解

しばしば抱かれる期待は、「古いライブラリに PDF 2.0 と署名をさせる何かのフラグがあるはずだ」というものです。そんなものはありません。これらは、成熟したライブラリが公開し忘れたオプションではありません。それは、そのアーキテクチャがそもそも中心に据えていなかった能力です。ライターが実装していないフォーマットの版や署名プロファイルに、設定で辿り着くことはできません。

その鏡像となる誤解は、NextPDF は 100% の TCPDF ドロップインであり、だから移行は無償だ、というものです。そうではありませんし、私たちはそうであるかのように振る舞いません。互換サーフェスは、移行を渡らせるために、API の実在する文書化された一部分をカバーします。一部の呼び出しは異なる振る舞いをし、いくつかは対象外です。それを、すべてのレガシースクリプトが手つかずで動く保証ではなく、公開された地図を備えた橋として扱ってください。

限界と境界

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ 互換サーフェスは、TCPDF と バイト単位で同一なのではなく、互換 です。移行中に既存の呼び出し箇所がファイルを生成し続けられるよう、API の文書化されたサブセットをカバーします。これはドロップインではなく橋です。一部の振る舞いは異なり、一部の呼び出しはサポートされていません。いずれもメソッドカバレッジと移行のページに一覧化されています。目的地は、標準準拠の出力が存在するネイティブの型付き API です。
Pro	●Available
Enterprise	●Available

移行は手段であって、美徳ではありません。あなたの文書が単純で、ライブラリがまだ保守されており、PDF 2.0、署名、PDF/A、アクセシビリティを必要とすることが決してないのなら、誠実な答えは今いる場所に留まることかもしれません — 切り替えコストは実在し、必要のない移行は、すべきでない移行です。NextPDF を使うべきでないときのページは、その線をひるむことなく引いています。

このページが説明するのは、移行の 道筋 とエンジンの 目標 です。正確な API カバレッジ、振る舞いの違い、そして手順ごとの段取りは、各呼び出しが何をするかについての権威である互換ドキュメントにあります。ここに書かれていることは、任意のレガシースクリプトが無変更で動くことを約束するものではありません。

関連ドキュメント

• What PDF 2.0 changed — 多くのレガシーライブラリが書き出せないフォーマットの版と、それがなぜ重要なのか。
• The TCPDF compatibility surface — 橋が何をカバーし、どこで異なるかについての権威あるガイド。
• When not to use NextPDF — 誠実な境界。必要のない移行はスキップできるように。
• One engine, every framework — 移行先のエンジンが、すでに動かしているスタックのどこにつながるか。

用語集

• PDF 2.0 — Portable Document Format 標準の現行版（ISO 32000-2）。初出時に展開。NextPDF がデフォルトで書き出すフォーマット。
• PDF/A — アーカイブ準拠ファミリー（ISO 19005 シリーズ）。PDF を長期保存に安全なものにする要件を定義します。ライターが生成しなければならない性質であり、呼び出し側があとから加えられるものではありません。
• PAdES — PDF Advanced Electronic Signatures。PDF に標準準拠の署名を埋め込むための ETSI プロファイルファミリー（EN 319 142）。初出時に展開。署名関連のページで詳しく扱います。
• 互換サーフェス（Compatibility surface） — ソースライブラリ（ここでは TCPDF）の形をした API レイヤーで、移行中に既存の呼び出し箇所を動かし続けます。オリジナルとバイト単位で同一ではなく互換 — ドロップインではなく橋です。
• ドロップイン代替（Drop-in replacement） — 既存のコードを無変更で動かす代替物。TCPDF 互換サーフェスは、意図的に この言葉では 説明されません。既知の振る舞いの違いを伴う、文書化された移行支援です。