高度な機能

基本的なHTML-to-PDFレンダリング以外にも、Artisanパッケージはドキュメントの結合、グローバルスタイルの注入、スクリーンショットのキャプチャ、Chromeの動作の詳細設定のためのユーティリティを提供しています。

PDFの結合

PdfMerger クラスは、複数のHTMLソースを単一のPDFドキュメントに結合します。各ソースは個別のセクションとしてレンダリングされ、結果は順番に連結されます。

use Yeeefang\TcpdfNext\Artisan\PdfMerger;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$merger = PdfMerger::create();

$merger
    ->addHtml('<h1>Cover Page</h1><p>Annual Report 2026</p>')
    ->addFile('/templates/chapter-1.html')
    ->addFile('/templates/chapter-2.html')
    ->addUrl('https://charts.example.com/annual-summary')
    ->addHtml('<h1>Appendix</h1><p>Supporting data tables.</p>');

$merger->save('/reports/annual-2026.pdf');

セクションごとのオプション

各セクションに独自の RenderOptions を設定できます。例えば、表紙を横向き、章を縦向きにすることができます。

$coverOptions = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(true)
    ->setPrintBackground(true);

$chapterOptions = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(false)
    ->setDisplayHeaderFooter(true)
    ->setFooterTemplate('
        <div style="font-size: 8px; text-align: center; width: 100%; color: #888;">
            Page <span class="pageNumber"></span>
        </div>
    ');

PdfMerger::create()
    ->addHtml('<h1>Cover</h1>', options: $coverOptions)
    ->addFile('/templates/chapter-1.html', options: $chapterOptions)
    ->addFile('/templates/chapter-2.html', options: $chapterOptions)
    ->save('/reports/merged.pdf');

CSS注入

StyleInjector クラスは、レンダリングされるページにCSSルールを前置します。制御できないテンプレートにグローバルなブランドスタイルシートを適用するのに便利です。

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\StyleInjector;

$injector = StyleInjector::create()
    ->addCss('
        body {
            font-family: "Inter", "Noto Sans TC", sans-serif;
            font-size: 11pt;
            line-height: 1.6;
            color: #333;
        }
        h1 { color: #1a237e; }
    ')
    ->addCssFile('/styles/brand.css');

HtmlRenderer::create()
    ->loadFile('/templates/report.html')
    ->withStyleInjector($injector)
    ->save('/output/branded-report.pdf');

複数のスタイルレイヤー

スタイルは追加された順番で注入されます。標準のCSS詳細度に従い、後のルールが前のルールを上書きします。

$injector = StyleInjector::create()
    ->addCssFile('/styles/reset.css')
    ->addCssFile('/styles/brand.css')
    ->addCss('table { page-break-inside: avoid; }');  // 上書き

スクリーンショット

ScreenshotCapture クラスは、PDFの代わりに画像フォーマットでHTMLをレンダリングします。サムネイルの生成、ソーシャルメディアプレビュー、ビジュアルリグレッションテストに便利です。

use Yeeefang\TcpdfNext\Artisan\ScreenshotCapture;

// フルページスクリーンショットをPNGで
ScreenshotCapture::create()
    ->loadHtml('<h1>Preview</h1><p>This will be a PNG image.</p>')
    ->fullPage(true)
    ->format('png')
    ->save('/output/preview.png');

JPEG（品質指定）

ScreenshotCapture::create()
    ->loadUrl('https://example.com/dashboard')
    ->format('jpeg')
    ->quality(85)
    ->save('/output/dashboard.jpg');

ビューポート設定

ScreenshotCapture::create()
    ->loadFile('/templates/email.html')
    ->viewport(width: 1200, height: 800)
    ->deviceScaleFactor(2)  // Retina
    ->fullPage(false)
    ->save('/output/email-preview.png');

Chrome設定

カスタムバイナリパス

ArtisanはOSの一般的なパスでChromeを自動検出します。chromePath で上書きできます。

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create(
    chromePath: '/opt/google/chrome/chrome',
);

または CHROME_PATH 環境変数をグローバルに設定してください。

ヘッドレスモードフラグ

Artisanはデフォルトで --headless=new（Chrome 112以降）を渡します。特定の環境向けに追加フラグを設定できます。

$renderer = HtmlRenderer::create(
    chromeFlags: [
        '--no-sandbox',            // Dockerで必須
        '--disable-gpu',           // Dockerで推奨
        '--disable-dev-shm-usage', // /dev/shmの問題を回避
        '--font-render-hinting=none',
    ],
);

コネクションプーリング

高スループットのシナリオでは、複数のレンダリングにわたって単一のChromeインスタンスを再利用します。これにより、後続の各レンダリングの起動コスト（約300〜500ミリ秒）が排除されます。

use Yeeefang\TcpdfNext\Artisan\ChromeBridge;
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

// 永続的なブリッジを作成
$bridge = ChromeBridge::create(chromePath: '/usr/bin/chromium');

// 複数のレンダリングで再利用
foreach ($reports as $report) {
    HtmlRenderer::createWithBridge($bridge)
        ->loadHtml($report->html)
        ->save("/output/{$report->id}.pdf");
}

// 完了したら明示的にクローズ
$bridge->close();

エラーハンドリング

すべてのArtisan例外は Yeeefang\TcpdfNext\Artisan\Exceptions\ArtisanException を拡張しています。

use Yeeefang\TcpdfNext\Artisan\Exceptions\RenderException;
use Yeeefang\TcpdfNext\Artisan\Exceptions\ChromeNotFoundException;
use Yeeefang\TcpdfNext\Artisan\Exceptions\TimeoutException;

try {
    HtmlRenderer::create()->loadUrl($url)->save($path);
} catch (ChromeNotFoundException $e) {
    // Chromeをインストールするか、CHROME_PATHを設定
} catch (TimeoutException $e) {
    // タイムアウトを増やすか、ネットワークを確認
} catch (RenderException $e) {
    // $e->getMessage() で詳細を確認
}

例外	一般的な原因
ChromeNotFoundException	Chromeがインストールされていない、CHROME_PATH が間違っている
TimeoutException	遅いページ、未解決のJSプロミス、ネットワークの問題
RenderException	無効なHTML、Chromeのクラッシュ、ディスク書き込み失敗

パフォーマンスのヒント

1. Chromeインスタンスを再利用 -- バッチ操作には ChromeBridge を使用しましょう。
2. JavaScriptを最小化 -- Chromeが実行するJSが少ないほど、レンダリングが速くなります。
3. 重要なCSSをインライン化 -- 可能な限り外部スタイルシートの取得を避けましょう。
4. タイトなタイムアウトを設定 -- 壊れたページでキューがブロックされるよりも早く失敗させましょう。
5. setPrintBackground(false) を使用 -- 不要な場合は背景レンダリングをスキップしましょう。

次のステップ

• レンダリングオプション -- ページサイズ、マージン、ヘッダー/フッターテンプレート。
• Docker設定 -- コンテナ環境でのArtisan実行。
• 概要 -- パッケージの概要とインストール。