LaravelでのPDF生成に苦しむのをやめる方法

Web上でPDFドキュメントを生成することは、常に大きな課題でした。Perfectな請求書やレポートを作成しようとして、フォントがずれたり、テーブルが崩れたり、画像が消えたりした経験が何度もあるでしょう。通常、選択肢はサーバー設定が必要なwkhtmltopdfのような複雑なシステムユーティリティと、有料のクラウドサービスに限られます。

Laravelスタックで作業しているなら、実績のあるソリューションがあります—Barry van den Heuvelによるlaravel-dompdfパッケージです。Dompdfライブラリのラッパーで、おなじみのBladeテンプレートを取得してPDFファイルに変換します。追加のサーバー依存関係は不要で、PHPだけで動作します。

内部の仕組み

このプロジェクトは本質的に1つのことを行います：Laravelの力とDompdfエンジンを結びつけます。主な特徴は、ドキュメントレイアウトのための新しい構文を学ぶ必要がないことです。通常のViewを作成し、データ渡すと、パッケージがレンダリングを処理します。

興味深いことに、このパッケージは標準的なLaravelだけでなくLumenもサポートしています。これはドキュメント生成を別のマイクロサービスに切り出す場合に便利です。

実際の動作

インストールはComposer経由では標準的です：

composer require barryvdh/laravel-dompdf

その後、Pdfファサードにアクセスできるようになります。ファイル作成の最もシンプルな例はこのようになります：

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('emails.invoice', ['order' => $order]);
return $pdf->download('invoice.pdf');

loadViewメソッドはBladeファイルを取得して変数渡し、ユーザーにダウンロードさせたり、stream()でブラウザに表示できるオブジェクトを生成します。

柔軟なページ設定

多くの場合、コード内でページ方向や用紙サイズを変更する必要があります。例えば、横向きは幅の広いテーブルに適しています：

Pdf::loadHTML($html)
    ->setPaper('a4', 'landscape')
    ->setWarnings(false)
    ->save('report.pdf');

ちなみに、ファイルをユーザーに提供する代わりにディスクに保存する必要がある場合は、save()メソッドが1行で完了します。

PDF/A-3bサポートと電子請求書

最近のバージョン（3.x）ではPDF/A-3b標準のサポートが追加されました。これは長期的なドキュメント保存に不可欠です。ただし、注意点があります：この標準ではすべてのフォントをファイルに埋め込む必要があります。標準のHelveticaやTimesでは動作しません—DejaVu Sansなどの使用が必要です。

会計自動化に取り組む方のために、パッケージはZugferdとFactur-X形式をサポートするようになりました。これは請求書データを含むXMLファイルがPDFに直接埋め込まれる形式です。 다음과 같습니다：

$pdf = Pdf::loadView('invoice', $data)->setPdfA();

// Добавляем метаданные для Factur-X
$pdf->setAdditionalXmpRdf($xmlMetadata);

// Прикрепляем сам XML
$pdf->addEmbeddedFile(
    storage_path('invoices/factur-x.xml'),
    'factur-x.xml',
    'Factur-X Invoice',
    'text/xml'
);

レイアウトのヒント

Dompdfは完全なブラウザエンジンではありません。CSS 2.1 잘 처리하며 일부 CSS 3 속성도 지원하지만, Flexbox나 Grid는 사용하지 마세요. 전통적인 테이블과 플로트가 가장 효과적입니다.

時間を節約する2つの重要なポイント：

1. テンプレートでは常にエンコーディングを指定してください：<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>。これがないとキリル文字が疑問符になります。
2. ページ分割にはCSSプロパティpage-break-after: alwaysを使用してください。これは必要な場所で印刷開始位置を制御する最も確実な方法です。

使用する価値はあるか

laravel-dompdfは堅実なツールです。シンプルから中程度の複雑さのドキュメント生成に最適です：請求書、サービステレポート、簡単な明細書など。

主な利点はシンプルさです。Node.js、Puppeteer、サーバーバイナリのインストールが不要です。標準的なPHPホスティングで箱から出してすぐに動作します。

ただし、複雑なJavaScriptチャートをレンダリングする必要がある場合、またはモダンなCSS技巧を活用したヘビーなレイアウトが必要な場合は、Dompdfでは苦労する可能性があります。そんな場合はChromiumベースのツールを検討することをお勧めします。しかし、バックエンド開発者のタスクの90%にとっては、このパッケージは十分すぎるでしょう。

このプロジェクトは活発にメンテナンスされており（GitHubで7,000スター以上）、Laravelコミュニティで最も有名な貢献者の一人によってサポートされています。まだ試していない方はぜひブックマークしておいてください。