Artisan 套件總覽

Artisan · LGPL-3.0

yeeefang/tcpdf-nextartisan 透過 Chrome DevTools Protocol（CDP）實現高保真的 HTML 轉 PDF 渲染。它能忠實地將任何瀏覽器可呈現的 HTML/CSS 轉換為 PDF，包括 Flexbox、Grid、Web Fonts、CSS 變數等完整的 CSS3 功能。

何時使用 Artisan vs Core

面向	Core（內建 HTML 解析器）	Artisan（Chrome CDP）
CSS 支援	基本子集（表格、行內樣式）	完整 CSS3（Flexbox、Grid、動畫）
Web Fonts	需手動嵌入 TrueType	自動載入 Google Fonts 等
JavaScript	不支援	完整支援（圖表、動態內容）
外部依賴	無	需要 Chrome / Chromium
渲染速度	極快（毫秒級）	較慢（需啟動瀏覽器程序）
適用場景	報表、發票、簡單版面	複雜版面、品牌設計、儀表板

經驗法則： 如果你的 HTML 在瀏覽器中看起來完美、但用 Core 渲染不理想，就改用 Artisan。

安裝

composer require yeeefang/tcpdf-nextartisan

Chrome / Chromium 安裝

Artisan 需要可執行的 Chrome 或 Chromium。在伺服器環境中，建議安裝無頭 Chromium：

# Ubuntu / Debian
sudo apt-get install -y chromium-browser

# Alpine（Docker 常用）
apk add --no-cache chromium

# macOS
brew install --cask chromium

快速開始

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

HtmlRenderer::create()
    ->loadHtml('<h1>Hello Artisan</h1><p>完整 CSS3 支援。</p>')
    ->save('/tmp/output.pdf');

套件內容

Artisan 套件包含以下 7 個核心類別：

類別	說明
HtmlRenderer	主要進入點 — 載入 HTML 並渲染為 PDF
RenderOptions	頁面設定 — 尺寸、邊界、頁首頁尾、縮放
PdfMerger	將多份 PDF 合併為單一檔案
StyleInjector	在渲染前注入額外的 CSS 樣式
ScreenshotCapture	將 HTML 渲染為 PNG / JPEG 截圖
ChromeProcess	管理 Chrome 子程序的生命週期
CdpConnection	底層 CDP WebSocket 連線管理

下一步

1. HTML 渲染器 — 從字串、檔案或 URL 載入 HTML 並渲染為 PDF。
2. 渲染選項 — 設定頁面尺寸、邊界、頁首頁尾與列印參數。
3. 進階功能 — PDF 合併、CSS 注入、截圖與錯誤處理。
4. Docker 設定 — 在容器中執行 Artisan 與 Chrome 的最佳實踐。