FPDI と FPDF を使った PHP での PDF 文書の結合
PHP で PDF を結合するには、FPDI で入力元の全ページをインポートし、FPDF でそれぞれに対応する出力ページを作成します。このコマンドラインの例では、ローカルの PDF を指定順に結合し、異なるページサイズを維持します。指定した入力を一つでもインポートできない場合は失敗します。サンプル PDF を二つ生成して結合し、結果の三ページを確認します。
前提条件
PHP 8.3–8.5、Composer 2、書き込み可能なローカルディレクトリを用意してください。このチュートリアルは、Linux の Bash シェルで PHP 8.5.10、Composer 2.10.3、FPDI 2.6.8、FPDF 1.9.0 を使って検証しています。
依存関係をインストールする前に、PHP CLI の GD 拡張と Zlib 拡張を有効にしてください。どちらも FPDF の Composer マニフェストに宣言されています。FPDI も Zlib を必要とします。php --ini で CLI の設定を、php -m で読み込み済みの拡張を確認してください。Web サーバーでは別の PHP 設定が使われる場合があります。
後述する独立した検証を実行する場合は、Poppler の pdfinfo と
pdftotext コマンドをインストールしてください。これらは結果を検証するもので、PHP の結合スクリプトの依存関係ではありません。
FPDI と FPDF のインストール
新しい pdf-merge-demo プロジェクトを作成する親ディレクトリで作業を始めます。
mkdir pdf-merge-demo &&
cd pdf-merge-demo &&
composer require --no-interaction 'setasign/fpdf:1.9.0' 'setasign/fpdi:2.6.8'
&& で連結したコマンドは、ディレクトリの作成や移動に失敗すると停止します。プロジェクトがすでに存在する場合は、別の名前を選んでください。セットアップをやり直すために既存のプロジェクトを削除しないでください。Composer が成功してから先に進み、再現可能なインストールのために、生成された composer.lock を保持してください。以下のスクリプトは pdf-merge-demo 内に保存し、以降のコマンドはすべてそのディレクトリで実行します。
サンプル PDF の生成
次の内容を samples.php として保存してください。A4 縦向きページと A3 横向きページを含む a.pdf と、US Letter 縦向きページを含む b.pdf を作成します。ラベルによってページの順序を確認しやすくしています。このサンプル生成スクリプトを再実行すると、チュートリアルのディレクトリ内にある
a.pdf と b.pdf が置き換えられます。
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
$samples = [
'a.pdf' => [['P', 'A4', 'A1'], ['L', 'A3', 'A2']],
'b.pdf' => [['P', 'Letter', 'B1']],
];
foreach ($samples as $name => $pages) {
$pdf = new FPDF();
foreach ($pages as [$orientation, $format, $label]) {
$pdf->AddPage($orientation, $format);
$pdf->SetFont('Helvetica', '', 20);
$pdf->Cell(0, 10, $label);
}
$pdf->Output('F', __DIR__ . '/' . $name);
}
php samples.php
FPDI による既存 PDF のインポート
FPDI は、インポートしたページの内容から新しい文書を作成します。setSourceFile() メソッドは、入力元のページ数を返します。以下の結合ループでは、各ページについて
importPage() を呼び出し、getTemplateSize() で寸法を取得して、その寸法と向きを
AddPage() に渡します。これらの引数なしで AddPage() を呼び出すと、代わりにデフォルトの A4 縦向きページが使われます。
デフォルトでは、importPage() は表示されるページ境界である
CropBox を使用し、必要に応じて MediaBox にフォールバックします。出力は入力元ページの回転も含め、インポートした領域に一致します。印刷用の個別のボックスは維持しません。FPDI のページ境界の実装を参照してください。
任意の数の PDF の結合
次の完全なスクリプトを merge.php として保存してください。mergeMany() は成功時に出力ページ数を返し、失敗時に例外をスローします。入力をスキップすることはありません。CLI は失敗を捕捉し、標準エラー出力にエラーを書き込み、ステータス 1 で終了します。
出力方針は、使い捨てのサンプル生成スクリプトとは異なります。結合処理では、入力ファイルも含め、既存の出力先への上書きを拒否します。出力を開く前に、全ページのインポートとシリアライズを完了します。PHP の xb ファイルモードは、新しいバイナリファイルを排他的に作成するため、再実行しても以前の結果は切り詰められません。
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use setasign\Fpdi\Fpdi;
function mergeMany(array $files, string $out): int
{
if ($files === []) {
throw new InvalidArgumentException('Provide at least one input PDF.');
}
$pdf = new Fpdi();
foreach ($files as $file) {
if (!is_file($file) || !is_readable($file)) {
throw new RuntimeException("Cannot read input PDF: $file");
}
$pageCount = $pdf->setSourceFile($file);
if ($pageCount < 1) {
throw new RuntimeException("Input PDF has no pages: $file");
}
for ($page = 1; $page <= $pageCount; $page++) {
$template = $pdf->importPage($page);
$size = $pdf->getTemplateSize($template);
$pdf->AddPage($size['orientation'], [$size['width'], $size['height']]);
$pdf->useTemplate($template);
}
}
// Serialization can fail too; do it before creating the destination.
$bytes = $pdf->Output('S');
$handle = @fopen($out, 'xb');
if ($handle === false) {
throw new RuntimeException("Cannot create output: $out (exists or is not writable).");
}
try {
if (fwrite($handle, $bytes) !== strlen($bytes) || !fflush($handle)) {
throw new RuntimeException("Could not write the complete PDF: $out");
}
} catch (Throwable $error) {
fclose($handle);
unlink($out);
throw $error;
}
fclose($handle);
return $pdf->PageNo();
}
try {
if ($argc < 2) {
throw new InvalidArgumentException('Usage: php merge.php OUTPUT.pdf INPUT.pdf ...');
}
$pages = mergeMany(array_slice($argv, 2), $argv[1]);
fwrite(STDOUT, "Merged $pages pages into {$argv[1]}\n");
} catch (Throwable $error) {
fwrite(STDERR, 'Merge failed: ' . $error->getMessage() . "\n");
exit(1);
}
Output('S')は、PDF のバイト列を文字列として返します。インポートやシリアライズに失敗しても、出力先は変更されません。書き込みの失敗を検出した場合は、新しく作成された不完全な出力を削除します。このローカルスクリプトは、クラッシュに耐える公開の仕組みではありません。書き込み中に中断されると不完全なファイルが残る可能性があるため、利用側では正常終了を待つ必要があります。
二つの PDF の結合
出力先を最初に指定し、その後に入力を希望する順序で並べてスクリプトを実行します。
php merge.php merged.pdf a.pdf b.pdf
Merged 3 pages into merged.pdf と表示され、ステータス 0 で終了するはずです。入力パスを増やす場合も同じコマンドを使います。空白を含むパスは引用符で囲んでください。これらのサンプルの順序を変更するには、別の出力先に書き込みます。
php merge.php reversed.pdf b.pdf a.pdf
reversed.pdf 内のラベルは、B1、A1、A2 の順になるはずです。入力元のファイルは変更されません。
結果と失敗時の動作の確認
pdfinfo -f 1 -l 3 merged.pdf &&
pdftotext -layout merged.pdf -
Pages: 3、以下のページ寸法、および
A1、A2、B1 の順に並ぶラベルを確認してください。PDF のポイントは 1/72 インチです。丸めによる小さな差異は正常です。
| ページ | ラベル | 用紙 | 幅 × 高さ(ポイント) |
|---|---|---|---|
| 1 | A1 | A4 縦向き | 595.28 × 841.89 |
| 2 | A2 | A3 横向き | 1190.55 × 841.89 |
| 3 | B1 | US Letter 縦向き | 612 × 792 |
存在しない入力があれば、その前後に有効な入力があっても、リクエスト全体が失敗する必要があります。missing.pdf が存在しない状態で、新しい出力先を指定してください。
php merge.php incomplete.pdf a.pdf missing.pdf b.pdf
このコマンドはステータス 1 で終了し、Cannot read input PDF: missing.pdf を報告します。incomplete.pdf は作成されません。読み取れないファイル、入力として指定したディレクトリ、不正な形式の PDF でも失敗します。出力パスだけを指定した場合は、入力リストが空のため失敗します。成功した結合コマンドを繰り返すと、merged.pdf が存在するため失敗します。そのバイト列は変更されません。両方の結果を残すには、新しい出力名を選んでください。
無料パーサーが維持できる内容の把握
ここで行うのは静的なページのインポートです。この例では、対話型フォームフィールド、注釈、クリック可能なリンク、ブックマーク、レイヤー、文書アクションはコピーしません。FPDI は、importPage() の importExternalLinks パラメーターで、外部 URI のリンク注釈を任意でインポートできますが、ここでのデフォルト値は false です。このオプションでは、フォーム、文書内ナビゲーション、その他の注釈は復元されません。
無料パーサーは、暗号化またはパスワード保護された PDF と、圧縮された相互参照ストリームやオブジェクトストリームを使用する PDF も拒否します。FPDF のサンプルにあるような、通常の圧縮されたページ内容には対応しています。PDF のバージョン番号だけでは、非対応の構造が含まれているかどうかは判断できません。これらの制限は FPDI の制限事項に記載されています。
非対応の圧縮に関するエラーが表示された場合は、互換性のある形式でエクスポートしたものを入手するか、Setasign のオプションの FPDI PDF-Parser アドオンを検討してください。パーサーを拡張しても、ページ内容のインポートが、文書全体の対話型機能を保持する結合に変わるわけではありません。それらの機能が必要な場合は、文書レベルの結合ツールを選んでください。
大きなファイルのメモリ管理
FPDF はメモリ内で出力を構築し、このスクリプトも保存中は
Output('S') が返した文字列を保持します。そのため、一度に一ページずつ処理しても、ストリーミング結合にはなりません。PHP のメモリ上限や処理単位のサイズを決める前に、代表的な入力でピークメモリ使用量を測定してください。PDF の数だけを基準にした信頼できる上限はありません。
処理後に FPDI オブジェクトを解放すると、そのリソースを解放できますが、結合後のガベージコレクションで、その処理のピークメモリ使用量を減らすことはできません。長時間稼働するワーカーでは、次の処理を始める前に、完了した処理のオブジェクトを解放してください。
