Artisanパッケージ
Artisan · LGPL-3.0Artisanパッケージ（yeeefang/tcpdf-nextartisan）は、Chrome DevToolsプロトコル（CDP）を活用したピクセルパーフェクトなHTML-to-PDF変換を提供します。Flexbox、Grid、Webフォント、メディアクエリ、レンダリング時に固定されるアニメーションを含む、完全なCSS3サポートでHTMLをレンダリングします。
Artisanを使うべき場面
| シナリオ | 推奨 |
|---|---|
| HTML/CSSテンプレートからPDFを生成 | Artisan |
| プログラマティックなPDF構築（セル、描画） | Core |
| HTMLメールをPDFアーカイブに変換 | Artisan |
| 構造化データからインボイス作成 | CoreまたはArtisan |
| 複雑なCSSレイアウト（Grid、Flexbox） | Artisan |
| 署名/暗号化されたPDF | Core |
仕組み
Artisanは、Chrome DevToolsプロトコルを介してヘッドレスChromeインスタンスを起動し、HTMLコンテンツをブラウザページに読み込み、Chromeの組み込みPDF印刷機能を使用します。つまり、ChromeがサポートするすべてのCSS機能がPDFで利用できます。限られたCSSパーサーと格闘する必要はもうありません。
HTML/CSS --> ChromeBridge --> Chrome CDP --> PDFバイナリ --> 保存 / ストリームインストール
bash
composer require yeeefang/tcpdf-nextartisan要件：
- PHP 8.2+
chrome-php/chrome ^1.15（自動的にインストール）- ホストにChromeまたはChromiumブラウザがインストールされていること
bash
# Ubuntu/Debian
apt-get install -y chromium-browser
# macOS
brew install --cask chromium
# Windows (Chocolatey)
choco install googlechrome
# 環境変数でカスタムパスを設定
export CHROME_PATH=/usr/bin/google-chromeクイックスタート
php
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
$renderer = HtmlRenderer::create();
$renderer
->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
->save('/output/hello.pdf');URLから
php
HtmlRenderer::create()
->loadUrl('https://example.com/report')
->save('/output/report.pdf');ファイルから
php
HtmlRenderer::create()
->loadFile('/templates/invoice.html')
->save('/output/invoice.pdf');パッケージの内容
| クラス | 用途 |
|---|---|
HtmlRenderer | メインエントリポイント — HTMLの読み込み、設定、レンダリング |
ChromeBridge | Chrome DevToolsプロトコル通信 |
RenderOptions | レンダリング設定（マージン、スケール、ヘッダー） |
PageSetup | レンダリング用のページサイズと向き |
PdfMerger | 複数のレンダリングページを単一のPDFに結合 |
StyleInjector | レンダリング前にCSSスタイルシートを注入 |
ScreenshotCapture | ページのスクリーンショット（PNG/JPEG）をキャプチャ |
例外階層
| 例外 | 発生条件 |
|---|---|
RenderException | 一般的なレンダリング失敗 |
ChromeNotFoundException | 想定されたパスにChromeバイナリが見つからない |
TimeoutException | ページの読み込みまたはレンダリングが設定されたタイムアウトを超過 |
すべての例外は Yeeefang\TcpdfNext\Artisan\Exceptions 名前空間に存在し、共通の ArtisanException 基底クラスを拡張しています。
CoreのHTMLパーサーとの比較
Coreパッケージには基本的なHTML-to-PDF変換のための HtmlParser モジュールが含まれています。依存関係のないソリューションが必要な場合はこちらを使用してください。完全なブラウザレンダリングの忠実性が必要な場合はArtisanを使用してください。
| 機能 | Core HtmlParser | Artisan |
|---|---|---|
| 外部依存関係 | なし | Chrome/Chromium |
| CSS Flexbox / Grid | いいえ | はい |
Webフォント（@font-face） | いいえ | はい |
| メディアクエリ | いいえ | はい |
| JavaScript実行 | いいえ | はい |
@page CSSルール | いいえ | はい |
| パフォーマンス（シンプルなドキュメント） | 高速 | 低速 |
| パフォーマンス（複雑なCSS） | 対応不可 | 信頼性が高い |
次のステップ
- HTMLレンダラー -- HTMLコンテンツの読み込みとレンダリング。
- レンダリングオプション -- ページサイズ、マージン、ヘッダー、フッターの設定。
- 高度な機能 -- PDFの結合、CSS注入、スクリーンショット。
- Docker設定 -- コンテナでのArtisan実行。