コンテンツにスキップ
getnextpdf.com

FPDF から NextPDF への移行

このガイドは、FPDF ベースのコードベースを NextPDF コアへ移行するのを助けます。FPDF は最も広く展開されているレガシーな PHP の Portable Document Format(PDF)ライブラリの 1 つであり、その描画サーフェス——手動の x/y カーソルで駆動される AddPageSetFontCellMultiCellWriteTextImageOutput——は、NextPDF 自身のセル/テキスト API にきれいに対応します。NextPDF の低レベル描画メソッドが同じ FPDF/TCPDF の系譜に従うためです。ただし NextPDF は FPDF の ドロップイン互換クローンではありません。それは厳格な型、フォントサブセット化、署名、PDF/A、アクセシビリティ(tagged PDF)を備えたモダンな PDF 2.0 エンジンです。2 つの実際の変化は、単位モデル(NextPDF は PDF ポイントで動作し、FPDF はデフォルトでミリメートル)と、出力動詞(FPDF の 'I'/'D'/'F'/'S' 文字の代わりに型付けされた OutputDestination enum)です。

コアに FPDF クラスのシムはありません。各呼び出しサイトを 動詞の対応付け を使って書き換えてください。代わりに TCPDF 6.x のコードベースに最小限の初期変更を望むなら、ほぼソース互換のドロップインパスを出荷する TCPDF 互換アダプター を参照してください。FPDF にはそのようなアダプターはありません。

Terminal window
composer require nextpdf/core:^3

移行中は setasign/fpdf(またはあなたの fpdf/fpdf)をインストールしたままにしておきます。最終的な切り替え後に削除してください(安全な移行手順を参照)。

FPDF と NextPDF は同じメンタルモデルを共有します。ページからなるドキュメント、カーソル(現在の x/y 位置)、そしてそのカーソルで描画するか、それを進める動詞です。SetXYCellLnMultiCell はいずれも両ライブラリでカーソルを読み取り、変更するため、ほとんどの手続き的な FPDF コードは行ごとに翻訳されます。

差分は偶発的ではなく意図的なものです。

  • 単位。 FPDF のコンストラクター(new FPDF($orientation, $unit, $size))はデフォルトでミリメートルです。NextPDF は PDF ポイントで動作します(1 pt = 1/72 in、ISO 32000-2 §7)。ドキュメント全体の単位つまみはありません——mm をポイントに 1 回変換してください(pt = mm * 72 / 25.4)。
  • Y 方向はあなたにとって同じまま。 FPDF と同様、NextPDF のユーザー座標は y = 0 をページ上部に置き、下向きに増加するため、カーソル演算はそのまま移植されます。NextPDF は内部で PDF ネイティブの左下原点に変換します。
  • 構築は明示的。 FPDF は方向、単位、サイズをコンストラクターに畳み込みます。NextPDF は不変の NextPDF\Core\Config 値オブジェクト(ページサイズ、マージン、フォントディレクトリ)と明示的な addPage() を取ります。
  • 常に Unicode、常にサブセット。 FPDF のコアビルドは Latin-1 であり、Unicode には tFPDF/UTF-8 バリアントを必要とします。NextPDF は全体を通して UTF-8 であり、フォントを 常に サブセットプログラムとして埋め込みます(ISO 32000-2 §9)。FPDF の AddFont/フォントメトリックファイルに相当するものはありません。TrueType/OpenType のフォントディレクトリを登録し、ファミリーを名前で選択してください。

以下で使われるコアのエントリーポイントは、Document::createStandalone()Document::addPage()Document::setFont()Document::cell()Document::multiCell()Document::text()Document::write()Document::ln()Document::image()、カーソルアクセサ(setXY/setX/setY/getX/getY)、Document::output(?string, OutputDestination)Document::save(string $path): voidDocument::getPdfData(): string、そして NextPDF\Core\Config 値オブジェクトです。これらのコアの描画、テキスト、出力メソッドの完全なリファレンスは、PHPDoc から自動生成される コアモジュールリファレンス索引 にあります。Html モジュール は HTML から PDF への関連読み物であり、このページの動詞のリファレンスではありません。

FPDF の公開メソッド名は長年使われ、よく知られています。以下の NextPDF 列は、コアソースのシグネチャに対して確認済みです(エビデンス / トレーサビリティを参照)。

FPDFNextPDFNotes
new FPDF($orient, $unit, $size)Document::createStandalone($config)方向/単位/サイズのコンストラクター引数は NextPDF\Core\ConfigpageSizemarginsfontsDirectory)になります。$unit はなし——ポイントで作業します。デフォルトの createStandalone() のページは A4 ポートレートです。
$pdf->AddPage($orient, $size)$doc->addPage($size, $orientation)直接対応。$sizePageSize 値オブジェクト、$orientationOrientation enum(Portrait/Landscape)です。
$pdf->SetFont($family, $style, $size)$doc->setFont($family, $style, $size)直接対応。$style は同じ ''/'B'/'I'/'BI'(加えて 'U' 下線)コードを使います。
$pdf->Cell($w, $h, $txt, $border, $ln, $align, $fill)$doc->cell($w, $h, $txt, $border, $newLine, $align, $fill)直接対応。$alignAlignment enum(Left/Center/Right/Justify)、$borderbool または 'LTRB' 文字列を受け取り、$lnbool $newLine になります。
$pdf->MultiCell($w, $h, $txt, $border, $align, $fill)$doc->multiCell($w, $h, $txt, $border, $align)実際のフォントメトリクスでワードラップします。$fill 引数はなし——背景が必要なら先に塗りつぶした rect() を描いてください。
$pdf->Write($h, $txt, $link)$doc->write($h, $txt, $link)カーソルから流れるテキスト。$link は URL リンク注釈を付加します。
$pdf->Text($x, $y, $txt)$doc->text($x, $y, $txt)絶対位置のテキスト。直接対応。
$pdf->Ln($h)$doc->ln($h)左マージンへの改行。0 = デフォルトの行高。
$pdf->Image($file, $x, $y, $w, $h)$doc->image($file, $x, $y, $w, $h)直接対応。$x/$y/$w/$h は null 許容(null = 現在のカーソル / 本来のサイズ)。
$pdf->SetXY($x, $y) / SetX / SetY$doc->setXY($x, $y) / setX / setY直接対応。getX()/getY() がカーソルを読みます。
$pdf->SetMargins($l, $t, $r)$doc->setMargins(new Margin($t, $r, $bottom, $l))1 つの Margin 値オブジェクト。コンストラクターの順序は (top, right, bottom, left) です——FPDF の (left, top, right) では ありません。FPDF の SetMargins には bottom 引数が なく(その bottom マージンは SetAutoPageBreak($auto, $margin) から来ます)、$bottom は自分で選びます——一般には top マージンと同じか、auto-page-break のマージンを渡します。
$pdf->SetAutoPageBreak($auto, $margin)$doc->setAutoPageBreak($auto, $margin)直接対応。
$pdf->SetDrawColor / SetFillColor / SetTextColor$doc->setDrawColor / setFillColor / setTextColorRGB (r, g, b)、またはグレースケール用の単一値。
$pdf->Line / Rect / SetLineWidth$doc->line / rect / setLineWidth直接対応。rect() はスタイル文字列('S'/'F'/'DF')を取ります。
$pdf->SetTitle/SetAuthor/SetSubject/SetKeywords/SetCreator$doc->setTitle/setAuthor/setSubject/setKeywords/setCreator直接対応。ISO 32000-2 §14 の情報辞書 / Extensible Metadata Platform(XMP)に着地します。
$pdf->Output($dest, $name)$doc->output($name, OutputDestination::…)FPDF の出力先文字(I/D/F/S)は OutputDestination enum に対応します。引数順序が入れ替わる ことに注意(NextPDF では name が先)。
$pdf->Output('S')$doc->getPdfData()PDF バイトを返します。
$pdf->Output('F', $path)$doc->save($path)ファイルパスに書き込みます。
$pdf->GetStringWidth($s)(no public method)文字列幅は cell()/multiCell() のラップ中に内部で計算されます。公開の文字列ごとの測定動詞はありません。手で測定する代わりに multiCell() を通じてラップを駆動してください。
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;
// FPDF:
// $pdf = new FPDF(); // mm, A4 portrait
// $pdf->AddPage();
// $pdf->SetFont('Arial', 'B', 16);
// $pdf->Cell(40, 10, 'Invoice');
// $pdf->Output('F', 'out.pdf');
// NextPDF — points, default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->setFont('Helvetica', 'B', 16.0);
$doc->cell(113.4, 28.3, 'Invoice', false, true, Alignment::Left); // ~40mm x ~10mm in points
$doc->save(__DIR__ . '/out.pdf');
echo "Wrote out.pdf\n";

この例は examples/04-text-and-fonts.php に整合します。明示的なページサイズ、マージン、登録されたフォントディレクトリ、そして FPDF コードベースがすでに使っているカーソル駆動のセルモデルを使います。

<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
// Equivalent of: new FPDF('P', 'mm', 'A4') + SetMargins(20, 16, 20)
// i.e. FPDF left=20mm, top=16mm, right=20mm. FPDF SetMargins has no bottom
// argument, so we pick bottom = top = 16mm. Convert each mm to points
// (pt = mm * 72 / 25.4): 16mm = 45.354pt, 20mm = 56.693pt.
// Margin constructor order is (top, right, bottom, left) — NOT FPDF's (L, T, R).
$config = new Config(
pageSize: new PageSize(595.276, 841.890, 'A4'),
margins: new Margin(45.354, 56.693, 45.354, 56.693), // top,right,bottom,left in points
fontsDirectory: __DIR__ . '/fonts',
);
$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->setAuthor('Finance');
$doc->addPage();
// SetFont + Cell, the FPDF way — but in points and with a real Unicode font.
$doc->setFont('DejaVuSans', 'B', 18.0);
$doc->setTextColor(30, 58, 138);
$doc->cell(0, 24.0, 'Quarterly Report', false, true, Alignment::Left);
$doc->setFont('DejaVuSans', '', 11.0);
$doc->setTextColor(0, 0, 0);
$doc->multiCell(0, 16.0, "Body text wraps on real font metrics. Unicode is "
. "native, so accented and non-Latin characters need no tFPDF variant — "
. "register the family in the fonts directory and select it by name.");
// Equivalent of $pdf->Output('D', 'report.pdf'):
$doc->output('report.pdf', OutputDestination::Download);
  • 単位。 FPDF からコピーするすべての数値座標、幅、高さ、マージンは、デフォルトでミリメートルです。移植中に 72 / 25.4 を 1 回だけ掛けてポイントを得てください。両者を混ぜると、すべてがひそかに誤ったサイズになります。
  • Output() の引数順序。 FPDF は Output($dest, $name)、NextPDF は output($name, $dest) です。出力先は文字ではなく OutputDestination enum です。ファイル / 文字列出力には save() / getPdfData() を優先してください。
  • SetMargins の順序。 FPDF は (left, top, right)、NextPDF の Margin 値オブジェクトは (top, right, bottom, left) です。書き写すのではなく、並べ替えてください。
  • フォント。 FPDF の AddFont() + .php メトリックファイルに相当するものはありません。TrueType/OpenType ファイルをフォントディレクトリに置き、ファミリー名で setFont() を呼んでください。コアの Base14 名(HelveticaTimesCourier)はファイルなしで解決します。PDF/A または tagged PDF の下では、それらは埋め込み可能なフォントに自動置換されます。
  • GetStringWidth 公開の文字列測定メソッドはありません。FPDF コードが列を手でレイアウトするために文字列を測定している場合は、そのブロックを multiCell()(メトリクスでラップ)または固定幅の cell() 呼び出しに切り替えてください。

NextPDF はコンテンツを単一のストリーミングパスで出力します(アーキテクチャ決定記録 ADR-001)。ピークメモリーは、保持されたオブジェクトツリーではなく、ドキュメントサイズを追跡します。このガイドの例の予算は wall_ms: 2000, peak_mb: 128 です。長いドキュメントの場合は、addPage() 呼び出しをまたいでコンテンツを駆動してください——FPDF のレポートがすでに使っているのと同じループの形です。

  • メタデータ。 SetTitle()/SetAuthor() は、ISO 32000-2 §14 の情報辞書 / XMP に書き込む型付きセッターに対応します。そこに秘密を決して保存しないでください。
  • 画像パス。 image() は、読み込み前にストリームラッパースキームと埋め込み NUL バイトを拒否します。アプリケーションが制御するパスを渡してください。
  • ドキュメント内コードなし。 NextPDF はドキュメント内のスクリプトを一切実行しません。FPDF の何もそれを変えません。
StatementSpecClause
ページ形式/方向はページ境界ボックスに対応する。ISO 32000-2§7
フォントは埋め込み/サブセットフォントプログラムとして書かれる。ISO 32000-2§9
タイトル / メタデータは情報辞書 / XMP に着地する。ISO 32000-2§14
線、矩形、画像はコンテンツストリームの描画である。ISO 32000-2§8

NextPDF は ISO 32000-2 のコンテンツを生成します。FPDF との視覚的な同一性は主張しません。レンダラーを変更するたびに出力を再レビューしてください。

該当なし。NextPDF コアは、ここで説明する FPDF 移行パスをカバーします。


サーバーサイドの手続き的な PDF 生成のために FPDF(または tFPDF)を運用しているチーム。コードが SetXYLn で駆動される AddPage / SetFont / Cell / MultiCell / Image / Output 呼び出しの並びであれば、動詞の対応付け があなたのサーフェス全体をカバーします。

スコープ内: FPDF の描画動詞、カーソルモデル、フォント、カラー、線と矩形、メタデータ、出力。スコープ外: FPDF の AddFont メトリックファイルツールと、サードパーティの FPDF スクリプト拡張(バーコード、回転、ブックマーク)——それらは対応する NextPDF モジュール(Barcode、Transforms、Navigation)に対応付けてください。ここでは扱いません。

挙動の互換性であり、ドロップインのシムではありません。コアは FPDF クラスのシムを提供しません。すべての呼び出しサイトを書き換えてください。NextPDF のセル/テキスト API が FPDF/TCPDF の系譜を共有するため動詞は密接に並びますが、単位モデル、Output の引数順序、Margin/enum 型が異なります——したがって書き写しは誤りで、翻訳が正しいのです。

FPDF constructNextPDFNotes
$unit'mm' デフォルト)(no equivalent)PDF ポイントで作業します。移植中に寸法を pt = mm * 72 / 25.4 で 1 回変換してください。
$orientation'P'/'L'addPage() 上の Orientation enum、または PageSize の幅/高さを入れ替えランドスケープ = 幅 > 高さ。
$size'A4'[w,h]Config->pageSizePageSize 値オブジェクト)名前付き形式は明示的なポイント寸法になります。PageSize::A4()A0()Letter/Legal のファクトリーが存在します。
SetMargins($l, $t, $r)Config->marginsMargin VO)コンストラクターの順序は (top, right, bottom, left)
AddFont($family, $style, $file)フォントディレクトリ + 名前による setFont()メトリックファイルを捨て、TTF/OTF を Config->fontsDirectory に置きます。
  • フォントディレクトリ。 FPDF のフォントごとの AddFont 登録は、フォントディレクトリに加えて setFont() のファミリーマッチングに集約されます。Config->fontsDirectory(デフォルトの検索パス)から始め、フォントが複数の場所にあるときは FontRegistry::addFontDirectory() または Document::addFontDirectory() で追加のディレクトリを登録してください。
  • 常に Unicode。 Latin-1 のデフォルトも別個の tFPDF ビルドもありません。UTF-8 入力が常態です。
  • 常にサブセット。 NextPDF は埋め込みフォントを常にサブセット化します(ISO 32000-2 §9)。FPDF のフォント埋め込みの選択に相当するものはなく、不要です。
  • グリフを再ベースライン化する。 フォントのマッチングとフォールバックはエンジン固有です。FPDF のフォントエイリアスには正確なファミリー名が必要な場合があります。置換の差分は欠陥ではなく想定内です。
  • 単位変換(mm → pt)——最も一般的な移植の間違い。上記を参照。
  • Output の引数順序が入れ替わり、出力先は enum になります。
  • Margin / Alignment / Orientation は型付きオブジェクト/enum であり、文字や位置指定の (l, t, r) の三つ組ではありません。
  • 公開の GetStringWidth なし——multiCell() を通じてラップを駆動します。
  • 独立したラスタライズ——密なコンテンツでの行ラップとページ分割が異なる場合があります。視覚的な差分を再ベースライン化してください。

これらは文書化された挙動の差分であり、どちらのエンジンの欠陥でもありません。

  • FPDF の $unit セレクター——モデル化されていません(常にポイント)。
  • AddFont() + .php/.z メトリックファイル——フォントディレクトリに置き換えられます。
  • GetStringWidth()——公開の文字列測定動詞はありません。
  • FPDF の 'I'/'D'/'F'/'S' 出力先文字——OutputDestination enum + save()/getPdfData() に置き換えられます。

これらに依存するコードはそのまま「移行」しません。上の行で表現し直してください。

  1. FPDF と並べて nextpdf/core を追加し、当面 FPDF をインストールしたままにします。
  2. 低リスクのドキュメントを 1 つ選びます。単位マップ でコンストラクターを変換し、動詞マップ で各動詞を移植します。すべての mm 座標をポイントに変換します。
  3. ドキュメントのフォントを Config->fontsDirectory に置いてファミリー名で選択し、AddFont 呼び出しを捨てます。
  4. 同じ入力で両方の PDF を生成し、視覚的に差分を取ります。差分(フォント置換、行ラップ)は独立したエンジンでは想定内です——ドキュメントごとに受け入れます。
  5. GetStringWidth ベースの手作業レイアウトを multiCell() または固定幅の cell() 呼び出しに置き換えます。
  6. リスクの低い順に、ドキュメントごとに繰り返します。最後の切り替えまで FPDF をインストールしたままにします。
  7. 最終的な切り替え後に FPDF を composer.json から削除します。
  • コードを変更する前に、代表的なドキュメントの FPDF 出力をスナップショットします(ゴールデン入力。バイトは異なります)。
  • 移行した各ドキュメントについて、自分自身のチェック(視覚的な差分 + テキスト抽出)で受け入れを表明します。NextPDF のセル/フォントの挙動は、examples/04-text-and-fonts.php とコアの tests/ の Font とテキスト出力スイートによって行使されます。移行の受け入れはドキュメント固有であり、あなたの責任のままです。
  • 移行したドキュメントごとにリグレッションテストを追加します。

このページのすべての NextPDF 挙動の記述は、リポジトリ内のソースシグネチャ、例、またはアーキテクチャ決定記録(ADR)によって、あるいは PDF 形式の性質についてはフロントマターの citations:適合性 テーブルの ISO 32000-2 条項によって、裏付けられています。FPDF の挙動は「独立したエンジン——文書化された差分を想定」としてのみ主張され、このページはリポジトリ内の成果物が証明しない同等性を一切主張しません。

NextPDF behavioral claimIn-repo evidence (path)
AddPageaddPage(?PageSize, Orientation): static に対応する。src/Core/Concerns/HasPages.phpaddPage())。
SetFont($family, $style, $size)setFont(string, string, float): static に対応する。''/'B'/'I'/'BI'/'U' スタイル。src/Core/Concerns/HasTypography.phpsetFont())。
Cellcell($w, $h, $txt, $border, $newLine, $align, $fill): static に対応する。src/Core/Concerns/HasTextOutput.phpcell())。
MultiCellmultiCell($w, $h, $txt, $border, $align): static(メトリックベースのラップ)に対応する。src/Core/Concerns/HasTextOutput.phpmultiCell()wrapText())。
Write/Text/Lnwrite()/text()/ln() に対応する。src/Core/Concerns/HasTextOutput.phpwrite()text()ln())。
SetXY/SetX/SetY/GetX/GetY は直接対応する。SetMarginsMargin VO を取る。src/Core/Concerns/HasPages.phpsetXY()getX()setMargins())。src/ValueObjects/Margin.php(top, right, bottom, left))。
Imageimage($file, ?$x, ?$y, ?$w, ?$h): static に対応する。スキーム/NUL パスを拒否する。src/Core/Concerns/HasImages.phpimage()assertImageFilePath())。
Line/Rect/SetLineWidth/SetDrawColor/SetFillColor/SetTextColor は直接対応する。src/Core/Concerns/HasDrawing.phpline()rect()setLineWidth())。src/Core/Concerns/HasColors.phpsetDrawColor()setFillColor()setTextColor())。
createStandalone() のデフォルトページは A4 ポートレート(595.276 × 841.890 pt)。src/Core/Document.phpcreateStandalone())。src/ValueObjects/PageSize.phpA4())。
出力先は OutputDestination enum(Inline/Download/File/String)。Output('S')getPdfData()Output('F', $p)save($p)src/Contracts/OutputDestination.phpsrc/Core/Concerns/HasOutput.phpoutput())。
SetTitle/SetAuthor/… は型付きメタデータセッターに対応する。情報辞書 / XMP に着地する。src/Core/Concerns/HasMetadata.phpsetTitle()setAuthor())。ISO 32000-2 §14(フロントマター citations:)。
フォントは常にサブセットプログラムとして埋め込まれる。src/Core/Concerns/HasTypography.phpbuildFontData())。ISO 32000-2 §9(フロントマター citations:)。
コンテンツは単一パスで出力される。docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md

両パッケージは最終的な切り替えまでインストールされたままなので、呼び出しサイトごとのロールバックは、その呼び出しサイトを FPDF パスに戻すことを意味します。最終的な切り替え後は、ロールバックは FPDF とバージョン管理から以前のコードを復元することを意味します。データ移行は伴いません。

パフォーマンスを参照。単一パスモデルは、保持されたバッファのコストを取り除きます。新しいドキュメントごとのコストは先行のフォント解決(手順 3)であり、これはフォントディレクトリを通じてキャッシュ可能です。

  • ミリメートル座標を * 72 / 25.4 の変換なしにポイントとして書き写すこと。
  • Output() を FPDF の ($dest, $name) の順序のまま残すこと、または OutputDestination enum の代わりに文字を渡すこと。
  • SetMargins($l, $t, $r) をそのまま Margin(その順序は top, right, bottom, left)に書き写すこと。
  • AddFont のメトリックファイルが移植されることを期待すること。代わりに TTF/OTF をフォントディレクトリに置いてください。
  • GetStringWidth の相当物に手を伸ばすこと。ラップには multiCell() を使ってください。
  • バイト/ピクセル単位で同一の出力を期待すること(独立したエンジン——このガイドはドロップインや 100% 互換性を一切主張しません)。