Artisan クイックスタート

概要

まず ChromeRendererConfig を NextPDF ドキュメントに関連付け、writeHtmlChrome() を呼び出して保存します。Chrome が HTML をレンダリングし、ブリッジがその結果を Form XObject としてインポートします。テキストは選択可能な状態で保持されます。

概念の概要

writeHtmlChrome() は NextPDF コアの Document メソッドで、HasTextOutput concern によって提供されます。このメソッドは入力を検証し、Artisan レンダラーを resolve（解決）して HTML を Chrome に送信し、返された PDF を解析したうえで、ページ 0 を現在のカーソル位置に Form XObject として埋め込みます。パブリックシグネチャは writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static です。この内容は nextpdf/coresrc/Core/Concerns/HasTextOutput.php で検証済みです。

コードサンプル — クイックスタート

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

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

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

これはパッケージの README.md に示されている標準的なフローです。flex レイアウトの処理は Chrome が担当します。ページがラスター画像ではなく Form XObject として埋め込まれるため、出力内の数値は選択可能なテキストのまま保持されます。

カスタムページサイズ

固定サイズのページに合わせるには、幅と高さを PDF ポイントで明示的に渡します（A4 の例です）。

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

幅と高さの両方を指定すると、Chrome はその用紙サイズどおりに印刷します。高さを省略する（または null を渡す）と、ブリッジは測定されたコンテンツの高さに自動的に合わせ、わずかなリフローの安全バッファを追加します。このバッファが存在する理由と、オーバーライドすべきタイミングについては、/integrations/artisan/production-usage/ を参照してください。

得られるもの

プロパティ	動作
テキスト	選択可能かつ検索可能（ラスタライズされていないベクターテキスト）
CSS	Chrome レイアウト — flexbox、grid、複雑なセレクター、data URI による Web フォント
ネットワーク	サブリソースのフェッチなし。リモート URL は読み込まれません（/integrations/artisan/security-and-operations/ を参照）
ページ	Chrome 出力のページ 0 のインポート

エッジケースと注意点

空の HTML では何も行いません。 writeHtmlChrome('') はドキュメントを変更せずに返します（HasTextOutput::writeHtmlChrome で検証済み）。
ページがまだない場合。 ページが存在しない場合、writeHtmlChrome() はレンダリングの前にページを 1 つ追加します。
リモートアセットは読み込まれません。 <img src="https://..."> は空の状態でレンダリングされます。アセットは data: URI としてインライン化してください。これはネットワーク分離の方針であり、バグではありません。/integrations/artisan/security-and-operations/ を参照してください。
ブリッジが見つからない場合。 nextpdf/artisan がインストールされていない場合、コアは致命的なエラーではなくレイアウト例外を発生させます。

パフォーマンス

最初の呼び出しでは、Chrome の起動とレイアウトのコストが発生します。以降の呼び出しでは、BrowserPool を介して稼働中の Chrome プロセスを再利用します。バッチ処理や長時間稼働するワーカーについては、/integrations/artisan/production-usage/ ページのライフサイクルとリソースに関するガイダンスを参照してください。

セキュリティに関する注意事項

このクイックスタートでは、信頼できるハードコードされた HTML を使用しています。ユーザー入力の影響を受ける HTML を writeHtmlChrome() に渡す前に、/integrations/artisan/security-and-operations/ をお読みください。ブリッジはネットワークアクセスを分離しますが、HTML レンダリングには依然として攻撃対象領域があります。

商用に関する背景

このフローでは、オープンソースのブリッジを使用して HTML から PDF を生成します。準拠した電子インボイス XML を同じドキュメントに埋め込めるよう、Premium Pro ティアでは埋め込みツールを提供します。Premium がなくても、オープンソースの経路には影響しません。