HTML から PDF へ、簡単な方法

このトラックではこれまで、呼び出しを 1 つずつ重ねてページを組み立ててきました。多くのドキュメントは、Web ページで使われるタグベースのテキスト形式であるマークアップで記述したほうが、手早く用意できます。このチュートリアルでは、 NextPDF に Hypertext Markup Language (HTML) を渡すと、エンジンがページを描画してくれます。

作成するもの

1 つの HTML 文字列からレンダリングされる、1 ページのレポートです。色付きの見出し、短い段落、そして合計行のあるテーブルを含みます。スタイルは、マークアップの見た目を制御するルール言語である Cascading Style Sheets (CSS) で指定します。これまでのチュートリアルでは、メソッド呼び出しを連ねる流暢な Application Programming Interface (API) を使いました。ここでは代わりに、レイアウトをマークアップで記述し、同じエンジンがそれをレンダリングします。

ステップ 1: HTML からスタイル付きレポートをレンダリングする

プロジェクトフォルダー内の vendor の隣に、01-html.php という名前のファイルを作成します。次の完全なスクリプトを貼り付けてください。

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

プロジェクトフォルダーからスクリプトを実行します。

php 01-html.php

出力が 1 行表示されるはずです。

Wrote out/reading-report.pdf

out/reading-report.pdf を任意の Portable Document Format (PDF) ビューアーで開きます。見出しは濃い青色で、テーブルのヘッダー行は同じ色で塗りつぶされています。

何が起きたか

@mkdir(__DIR__ . '/out'); は出力フォルダーを作成します。@ 記号はフォルダーがすでに存在する場合の警告を抑制するため、繰り返し実行しても余計な警告は出ません。
Document::createStandalone()、setTitle()、addPage() は、これまでのチュートリアルとまったく同じように動作します。マークアップに切り替えても、ドキュメントのセットアップは何も変わりません。
writeHtml() は文字列を上から下へ一度だけ読み取り、各要素を現在の位置に描画します。見出しと段落はスタイル付きのテキストになります。テーブルは、罫線付きセルで構成され、寸法が計算された行になります。
インラインの style 属性が CSS を保持します。エンジンは color、 background-color、text-align、width といった一般的なプロパティを理解します。
ブラウザーも追加のソフトウェアも関与しません。パイプラインはエンジン内部の純粋な PHP であるため、スクリプトは Composer のインストール先であればどこでも実行できます。

エンジンは、ブラウザーが受け付けるすべてではなく、実用的な HTML と CSS のサブセットをサポートします。そのサブセットの範囲外のものは、エラーを発生させるのではなく、黙ってスキップされます。CSS サポートマトリクスには、何が対象となるかが正確に記録されています。このパイプラインをより詳しく知りたい場合は、HTML を PDF ページにレンダリングするを参照してください。

HTML を使う場合と流暢な API を使う場合

どちらの方法も同じエンジンで動作するため、ドキュメントに合うほうを選んでください。

ドキュメントが Web ページのように読める場合、つまり見出し、段落、リスト、テーブルで構成される場合は writeHtml() を選びます。マークアップは記述が速く、チームメンバーが編集するのも容易です。
固定位置や精密に寸法を測ったセルなど、正確な配置が必要な場合は流暢な API を選びます。マークアップは流し込みを、流暢な呼び出しは細かな制御をもたらします。
プロパティに頼る前に、CSS サポートマトリクスを確認してください。スタイルが対象外の場合は、その部分を代わりに流暢な呼び出しで構築します。

安全性の境界

実際の HTML は、たとえばフォームやデータベースなど、コードの外部から来ることがよくあります。それを信頼できない入力として扱い、レンダリングの前に検証またはクレンジングしてください。デフォルトでは、組み込みのパイプラインはスクリプトを実行せず、リモートリソースも取得しません。このデフォルトにより、マークアップの内容にかかわらず、レンダラーは安全側で動作し続けます。ブラウザー並みのレンダリングオプションが必要な場合は、進む道を選ぶを参照してください。

うまくいかなかった場合

Failed to open stream: No such file or directory は通常、スクリプトが vendor/autoload.php を見つけられないことを意味します。Composer を実行したフォルダーから実行してください。
スタイルが反映されない場合、たいていはサポートされているサブセットの範囲外のプロパティです。エンジンは失敗するのではなく、サポートしていないものをスキップします。ご自分のマークアップを CSS サポートマトリクスと照らし合わせてください。
レンダリング中の例外は、問題の内容を正確に示します。レンダリングと入出力のエラーリファレンスで調べてください。

それ以外については、トラブルシューティングガイドから始めてください。

次のステップ

これで、呼び出しを 1 つずつ重ねる方法でも、マークアップからでも、ドキュメントを構築できるようになりました。次に進む先でこのトラックを締めくくりましょう。このトラックの後に使うことになる Cookbook、リファレンス、そしてガイドへの道筋を示しています。