跳轉到

Artisan — Chrome CDP 渲染套件

NextPDF Artisan

nextpdf/artisan 以 Chrome DevTools Protocol（CDP）為核心，將任意 HTML/CSS 頁面無損轉換為 PDF 2.0 文件。套件包含三個主要子系統：ChromeRenderer（渲染引擎）、BrowserPool（連線池管理）與 PdfParser（PDF 解析器），可獨立使用，亦可協同運作。

PHP Compatibility

This example uses PHP 8.5 syntax. If your environment runs PHP 8.1 or 7.4, use NextPDF Backport for a backward-compatible build.

與 NextPDF Core 的原生排版引擎不同，Artisan 將渲染任務委派給真實的 Chromium 瀏覽器實例，適合需要完整 CSS3 支援（Flexbox、Grid、變數、動畫快照）的場景。

核心能力

子系統 主要功能
ChromeRenderer HTML→PDF、CSS3 完整支援、CSP 沙箱、CDP 安全通道
BrowserPool 連線池、健康檢查、逾時控管、Octane 安全
PdfParser xref table 解析、FlateDecode 解壓、物件流提取
PageImport 以 Form XObject 將解析頁面嵌入 Core 文件

快速開始

composer require nextpdf/artisan

需要在本機或 Docker 容器中執行 Chromium 或 Google Chrome。

<?php

declare(strict_types=1);

use NextPDF\Artisan\BrowserPool;
use NextPDF\Artisan\ChromeRenderer;
use NextPDF\Artisan\Config\BrowserPoolConfig;
use NextPDF\Artisan\Config\RendererConfig;

// 建立連線池（建議在應用程式啟動時初始化一次）
$pool = BrowserPool::create(
    config: BrowserPoolConfig::create(
        chromiumBinary: '/usr/bin/chromium-browser',
        maxConnections: 4,
        idleTimeoutSeconds: 60,
    ),
);

// 建立渲染器
$renderer = ChromeRenderer::create(pool: $pool, config: RendererConfig::default());

// 渲染 HTML 字串為 PDF bytes
$pdfBytes = $renderer->renderHtml(
    html: '<h1>Hello, Artisan!</h1>',
    pageFormat: 'A4',
);

file_put_contents('/tmp/output.pdf', $pdfBytes);

BrowserPool 連線池

BrowserPool 負責管理與 Chrome 實例之間的 WebSocket 連線，確保並行渲染時不會建立過多瀏覽器程序。

use NextPDF\Artisan\BrowserPool;
use NextPDF\Artisan\Config\BrowserPoolConfig;

$pool = BrowserPool::create(
    config: BrowserPoolConfig::create(
        chromiumBinary: '/usr/bin/chromium-browser',
        maxConnections: 8,
        acquireTimeoutMs: 5000,
        healthCheckIntervalSeconds: 30,
    ),
);

PDF 解析器

PdfParser 可讀取既有 PDF 檔案，提取頁面結構以供 PageImport 使用：

use NextPDF\Artisan\PdfParser;

$parser = PdfParser::fromFile('/path/to/source.pdf');
$pages  = $parser->pages(); // list<ParsedPage>

安全考量

Artisan 在沙箱模式下啟動 Chrome，並透過 Content Security Policy 限制渲染範圍，防止 SSRF 與惡意 HTML 注入。詳見 Chrome 渲染器安全。

參見