laravel-dompdfでレイアウトを崩さない・意図しない改ページを防ぐための注意点まとめ｜ブログ

はじめに laravelで作成するWebアプリケーションの開発において、「登録したデータをPDF化して保存・出力する」という機能を実装する際、ライブラリを頼るケースは多いと思います。 今回、私はそのPDF化の手段としてlaravel-dompdfを採用したのですが……正直、思い通りにレイアウト調整ができず、めちゃくちゃ苦しい戦いを強いられました。 この記事では、そんな私のリアルな苦戦経験をもとに、得られた知見や注意点をまとめています。今まさに同じ沼にハマり、画面の前で頭を抱えている方の参考になれば幸いです。 まずlaravel-dompdfとは？ laravel-dompdfは、Laravelで手軽にPDFを出力できるようにするためのパッケージ（ラッパー）です。HTMLや使い慣れたBladeテンプレートから、直感的にPDFを生成できるのが最大の特徴です。 最大の強みは、PHP環境のみで完結する点にあります。サーバー側にNode.jsやLinuxのバイナリなど特殊なツールを別途インストールする必要がないため、インフラ側のトラブルが起きにくくデプロイも簡単です。 さらに専用のファサード（Pdf::）を使えば、コントローラーからわずか数行でPDFの生成やダウンロードを実装できるため、学習コストもかかりません。 しかし、モダンなCSSがほとんど使えず、最新ブラウザのように「いい感じに解釈してくれる」わけではないため、PDFのレイアウトが崩れやすいという欠点があります。 そもそもdompdfとは laravel-dompdfの背景にあるコアなライブラリがdompdfです。これは「HTMLとCSSを解析してPDFをレンダリングする」という仕組みを持っています。 しかし、普段私たちがブラウザで見ているWebページと、印刷物であるPDFとでは、根本的に構造が異なります。dompdfを扱う上で、特に以下の特性を理解しておく必要があります。 容赦のない改ページの考え方 ブラウザは縦に無限にスクロールできますが、PDFには「ページの高さ」という絶対的な限界があります。dompdfは要素の高さや配置を計算し、ページの境界に達すると容赦なく改ページを行います。この制御が非常にシビアです。 文字の大きさによる改行位置の自動調整 フォントサイズや文字列の長さに応じて、自動で改行位置が計算されます。ほんの数ピクセルのズレで文字が溢れ、それが原因でドミノ倒しのように全体のレイアウトが次ページへ押し出されることが多々あります。 HTMLからPDFを作成する限界 最新のブラウザのように「いい感じにCSSを解釈してくれる」わけではありません。あくまで「古いHTMLレンダリングエンジン」が裏で動いているイメージを持つ必要があります。 なぜ崩れる？Dompdfのテキスト・ボックス計算の裏側（仕様） 「CSSを正しく書いているはずなのに、なぜか数ピクセルズレて改ページされる……」 その原因は、Dompdfの内部的な仕様（テキストやボックスの計算方法）の可能性があります。 フォントメトリクス（文字ごとの正確な幅） Dompdfは、読み込まれたフォントデータに基づいて「A」と「i」の幅が異なるようなプロポーショナルフォントの文字幅（メトリクス）を内部で計算して描画しています。 そのため、「文字数が同じだから同じ幅に収まるだろう」という計算は通用しません。 入力される文字列（アルファベット、数字、日本語の混ざり具合）によって、全体の横幅は微妙に伸縮します。 CSSボックスモデルと行送り（line-height） padding（余白）、border（枠線）、marginの計算には対応しています。また、行送り（line-height）も内部的な基準値（デフォルトの比率など）を持って計算されています。 これらがすべて「掛け算・足し算」されて最終的な全体の「高さ」が決まるため、少しのパディングや行間の設定が、ページ最下部での「容赦ない改ページ」の引き金になります。 日本語の「禁則処理」には非対応 Dompdfはもともと欧文ベースのレンダリングエンジンであるため、日本語特有の「禁則処理（句読点『、。』や閉じ括弧を文頭に置かないルール）」には対応していません。 指定した横幅の右端に達すると、機械的にテキストをぶった切って折り返すため、文頭に「。」が来るような不自然な改行がそのまま描画されます。 この「禁則処理が効かない」「文字によって幅が変わる」という仕様があるため、Dompdfで綺麗なレイアウトを保つには、システム側で「表示する文字数を厳しく制限する」というアプローチが、一番確実で理にかなった対策になります。 PDF化するレイアウトのデザインを決める時には もしあなたがデザインを作成する場合、あるいはデザイナーやクライアントからデザインをもらう場合は、「最初からdompdfの限界を共有しておく」ことで調整で苦しむ時間が減らせるかもしれません。 もし、そういったことがあれば以下の点を気にしてレイアウトを作成してみてください。 2ページ目に突入しても崩れないシンプルなレイアウトが基本 Dompdfはページの高さに収まらないと判断した要素を容赦なく次のページへ送ります。 「絶対にこの1ページに収める」「ミリ単位で位置を固定する」といった厳密な調整はほぼ不可能です。そのため、「2ページ目に突入してもデザインが破綻しない」ような、縦に伸びても問題ないシンプルなレイアウトを最初から設計しましょう。 rowspan（縦のセル結合）を使った複雑なテーブル構造は避ける テーブル内で縦方向にセルを結合する rowspan は、dompdfの最大の天敵です。 結合されたセルがページの境界（最下部）をまたいだ瞬間、内部の高さ計算がバグり、要素が丸ごと消えたり、重なって表示されたりします。 デザイン段階で、できるだけ単純な行（ ）の積み重ねで表現できるよう調整しましょう（※横の結合である colspan は基本的に問題ありません）。 CSS頼みの複雑なレイアウトは組まない（使わない方がいいCSS） display: flex や grid などのモダンなCSSは適用されません。以下のプロパティを避けたレイアウトを検討してください。 | プロパティ | 挙動・注意点 | | --- | --- | | display: flex / grid | 原則使用不可。 レイアウトが完全に崩れるので table や float で代用。 | | position: absolute | 限定的に使用可能。 ただし、ページをまたぐ要素で使うと高確率でバグる。 | | page-break-inside: avoid; | 要素内での改ページ禁止。 trなどに使うと要素ごと消滅するバグの原因に。 | PDF化するHTML（Bladeファイル）を作る時の注意点 では実際にPDF化するHTMLファイルを作成するときには、以下に記載する点に注意して作成してみてください。 CSSは外部ファイル化せず、すべて1つのHTMLファイルに記述する 別ファイルのCSSを読み込ませようとすると、パスの解釈エラーや読み込み速度の影響でスタイルが適用されないトラブルが頻発します。基本は1つのBladeファイル内に完結させます。 box-sizing: border-box; を指定する（※ただし過信は禁物） paddingなどによる「段落ち（要素が下にずれる現象）」を防ぐために指定しておいた方が安心です。 { box-sizing: border-box; } ※ただし、dompdf の仕様上、table や td などの要素には正しく適用されないケースがあるため、テーブル幅に関しては、実際の動作を確認しつつ微調整してください。 横並びのレイアウトを作成する場合 要素を横に並べたいときは、table タグでも可能ですが、 float: left; を使用し、幅を % で指定するのが安定します。 また、float を使用したら、後ろの要素が巻き込まれてレイアウトが崩れるのを防ぐため、直後に を挟んで回り込みを物理的に解除（クリア）しておきましょう。 左側のコンテンツ 右側のコンテンツ // クリア用タグ ここから通常のテキスト（上のfloatに巻き込まれません）

※物理クリアはどんな時でも100%必須というわけではありません。例えば以下のようなケースでは、わざわざ空タグを挟まなくても自動で回り込みが切れることがあります。しかし、dompdf が思わぬ挙動をするのを防ぐための「一番打率の高い安全策」として、横並びの直後には常に仕込んでおくのがおすすめです。 float した親要素自体に高さがしっかり確保されている場合 次に続く要素にも最初から float: left; や clear: both; が指定されている場合 その横並びの後に、もう二度と他の要素（テキストなど）が続かず、ページが終了する場合 page-break-before / page-break-after での強制改ページ制御 「ここからは絶対に次のページに送りたい」「1枚目と2枚目の境界線をハッキリさせたい」という位置には、意図的に改ページを指示するCSSを挟みます。 dompdfで一番打率が高く、レイアウトが崩れない最強の書き方は、「改ページ専用の空のdivタグ」を用意して、そこに page-break-after: always; を指定する方法です。 / 強制的に改ページを入れるための専用クラス / .page-break { page-break-after: always; / この要素の後ろで強制改ページ / } 1ページ目のコンテンツです。

ここから2ページ目のコンテンツになります。

※この改ページ用タグ（ ）は、必ず「要素と要素のあいだ（フラットな階層）」に記述してください。 の内部などに無理やり挟むと、dompdf の計算がバグを起こして表示崩れの原因になります。 プレビュー機能（検証時におすすめ） PDFを調整する際に、何度もPDFファイルをダウンロードして、開いてというのが結構面倒になります。ささやかかもしれませんが、開発中は、コントローラーの出力を download() から stream() メソッド に変更して確認するのも、おすすめです。 // ダウンロードする場合（本番用など） return $pdf->download('invoice.pdf'); // プレビュー表示をする場合（開発・検証時におすすめ） return $pdf->stream('invoice.pdf'); おわりに 私が担当した案件では、レイアウト調整に調整を重ねていましたが、レイアウトが崩れないように、1ページに必ず収めたいといった要望が強かったため、最終的には別のライブラリに切り替えて対応することになりました。 結果としてlaravel-dompdfでの実装は見送ることになりましたが、dompdfの仕様やPDFレンダリングの仕組みについて、かなり深い知識を得ることができました。 この記事が、未来の自分、そして今まさに同じ苦労をして画面の前で頭を抱えている誰かに届いたら幸いです。「俺の屍を越えてゆけ」という気持ちを込めて。 この苦労話を書くことで、私のあの数日間の格闘も少しは昇華された気がします。 皆さんのPDF実装がうまくいくことを祈っています！