Artisan API 參考文件

概覽

Artisan 套件（nextpdf/artisan）公開兩組彼此相關的 API：Chrome 算繪介面（ChromeRendererConfig、ChromeHtmlRenderer、ChromeSecurityPolicy、ChromeRenderResult、ViewportCalculator、BrowserPool），負責將 HTML 片段轉成由 Chrome 產生的 PDF；以及範圍狹窄的 parser/importer 介面（PdfReader、PageImporter、ImportedFormXObject，以及輔助用 tokenizer/xref 類別），負責將算繪輸出嵌回 NextPDF 文件，形成文字可選取的 Form XObject。

先從這裡開始：如果你只是要把 HTML 轉成 PDF，幾乎不需要直接使用這個套件。請把 ChromeRendererConfig 附加到 NextPDF Document，再呼叫 writeHtmlChrome()（見快速入門）。只有在你需要把 renderer（渲染器）嵌進 worker，或執行剖析診斷時，才需要使用下列類別。「常見任務」下的第一個範例示範的就是這條單次呼叫路徑。

常見任務

下列三種流程涵蓋幾乎所有實際用法，從最高階的單次呼叫，一直到顯式的算繪與匯入管線。每個範例都已對照 nextpdf-Artisan/src 驗證（也對照套件的 README.md / ci/tests/）。

將 HTML 片段算繪成文字可選取的 PDF：這就是標準呼叫。

<?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"><h2>Revenue</h2><p>$124,500</p></div>');
$doc->save('/tmp/report.pdf');

用途：由 Chrome 負責片段排版，再由橋接層將第 0 頁嵌入為 Form XObject，讓文字保持可選取。writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static 會在 $height 為 null 時自動調整高度。

自行執行 renderer 並匯入頁面：這就是 writeHtmlChrome() 背後的顯式管線，適用於 worker 與自訂擺放。

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ImportedFormXObject;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(renderTimeout: 30));

try {
    $result = $renderer->render($html, widthPt: 595.28);

    $reader = new PdfReader($result->getPdfData());
    $reader->parse();

    $form = (new PageImporter())->import($reader);
} finally {
    $renderer->close();
}

用途：先算繪為 Chrome PDF 位元組並加以剖析，再將第 0 頁匯入為可供你擺放的 ImportedFormXObject。務必 close() renderer，以釋放 Chrome 程序。

使用 Framework（框架）風格的陣列建構組態：適用於 config/*.php 或套件參數，而不是寫死的建構式引數。

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;

$config = ChromeRendererConfig::fromArray([
    'chrome_binary'  => '/usr/bin/chromium',
    'render_timeout' => 45,
    'max_html_size'  => 2_000_000,
    'no_sandbox'     => false,
]);

用途：將 snake-case 組態陣列映射到建構式；未設定的鍵會退回預設值，而 chrome_binary 只有在值為非空字串時才會套用。

Chrome renderer（渲染器）

這些型別負責啟動並執行單次算繪：先建構一個 ChromeRendererConfig，交給一個 ChromeHtmlRenderer，再呼叫 render() 取得一個 ChromeRenderResult。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`new ChromeRendererConfig(?string $chromeBinaryPath = null, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, bool $noSandbox = false)`	執行檔路徑、逾時、CSS、HTML 大小上限、沙箱旗標。	當執行檔路徑為 `null` 時自動偵測 Chrome；除非明確停用，否則沙箱維持啟用。	`ChromeRendererConfig`	預期不會發生。	只有在執行環境需要時，才設定 `noSandbox`。
`ChromeRendererConfig::fromArray(array $config)`	`chrome_binary`, `render_timeout`, `default_css`, `max_html_size`, `no_sandbox`。	缺少的值會套用建構式的預設值。	`ChromeRendererConfig`	型別不符時，選用鍵會退回預設值。	對應 Framework 風格的組態陣列。
`new ChromeHtmlRenderer(ChromeRendererConfig $config, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null)`	組態、選用的 logger，以及選用的剖析層 HTML 政策。	未提供政策時，使用 `DefaultHtmlSecurityPolicy`。	`ChromeHtmlRenderer`	Chrome 設定錯誤會在第一次算繪時出現。	renderer 會持有瀏覽器集區，直到 `close()` 為止。
`ChromeHtmlRenderer::render(string $html, float $widthPt, float $heightPt = 0)`	`html`：輸入片段；`widthPt`：紙張寬度；`heightPt`：目標高度或自動。	當 `heightPt <= 0` 時自動計算內容高度。	`ChromeRenderResult`	`ChromeRenderException`；HTML 大小驗證失敗。	透過 CDP 阻擋子資源的網路請求。
`ChromeHtmlRenderer::getHtmlSecurityPolicy()`	無。	回傳已設定的剖析層政策。	`HtmlSecurityPolicyInterface`	預期不會發生。	與 Chrome 傳輸層的控管互補。
`ChromeHtmlRenderer::close()`	無。	關閉並清空瀏覽器集區。	`void`	底層函式庫可能拋出瀏覽器關閉錯誤。	在 worker 關閉時呼叫。

HTML 安全性政策

如果你要在算繪前自行驗證並包裝外部 HTML，而不是走 ChromeHtmlRenderer::render()，才需要使用這些 API（後者已經會呼叫它們）。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`ChromeSecurityPolicy::validate(string $html, int $maxSize)`	HTML 輸入與最大位元組大小。	只有當大小與不允許的結構都通過驗證時，才接受輸入。	`void`	`ChromeRenderException` 或驗證例外。	接受外部 HTML 時，在瀏覽器算繪前先執行。
`ChromeSecurityPolicy::wrapHtml(string $html, int $viewportWidth, string $defaultCss = '')`	HTML 片段、viewport 寬度，以及選用的預設 CSS。	將片段包裝成完整的算繪文件。	`string`	驗證或字串組建錯誤。	讓 renderer 專屬的 CSS 與應用程式 HTML 分離。

結果與轉換輔助

使用這些方法讀取單次算繪的輸出（ChromeRenderResult），並在設定 viewport 尺寸或計算高度時，於 PDF 點與 Chrome CSS 像素之間換算。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`new ChromeRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightCssPx)`	原始 PDF 位元組、寬度、高度，以及量測到的內容高度。	除了具型別的建構式屬性之外，不做額外驗證。	`ChromeRenderResult`	預期不會發生。	通常由 `ChromeHtmlRenderer::render()` 回傳。
`ChromeRenderResult::getPdfData()`	無。	回傳 Chrome 產生的原始 PDF 位元組。	`string`	預期不會發生。	嵌入時，搭配 `PdfReader` 與 `PageImporter` 使用。
`ChromeRenderResult::getWidthPt()`	無。	回傳所要求的寬度（以點為單位）。	`float`	預期不會發生。	用來決定匯入 form 物件的尺寸。
`ChromeRenderResult::getHeightPt()`	無。	回傳計算出或所要求的高度（以點為單位）。	`float`	預期不會發生。	自動高度會納入列印版面的緩衝量。
`ViewportCalculator::pointsToCssPx(float $pt)`	`pt`：PDF 點。	以每 72 PDF 點對應 96 CSS px 進行換算。	`int`	預期不會發生。	為配合 Chrome 的 viewport 寬度而取整。
`ViewportCalculator::cssPxToPoints(float $px)`	`px`：CSS 像素。	以每 96 CSS px 對應 72 PDF 點進行換算。	`float`	預期不會發生。	用於自動高度計算。

匯入與剖析 API

這是核心匯入路徑：先用 PdfReader 剖析 Chrome PDF 位元組，再把 reader 交給 PageImporter::import() 取得可嵌入的頁面；其餘 PdfReader 方法則用於診斷。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`new PdfReader(string $data)`	`data`：完整的 PDF 位元組。	呼叫 `parse()` 前不會執行剖析。	`PdfReader`	預期不會發生。	專為 Chrome 產生的 PDF 設計。
`PdfReader::parse()`	無。	剖析 xref 鏈與 trailer。	`void`	`PdfParseException`：當 PDF 結構無效時。	存取 object/page 之前必須先呼叫。
`PdfReader::getObject(int $objNum)`	物件編號。	依編號 resolve（解析）對應的已剖析物件。	`PdfObject`	`PdfParseException`：當物件不存在或格式錯誤時。	在 `parse()` 之後使用。
`PdfReader::getTrailer()`	無。	回傳已剖析的 trailer 字典。	`array`	`PdfParseException`：當 trailer 資料無法取得時。	供診斷與修訂分析使用。
`PdfReader::getObjectNumbers()`	無。	回傳已剖析的物件編號。	`array`	剖析後預期不會發生。	對匯入器的診斷很有用。
`PdfReader::getPage(int $pageIndex)`	`pageIndex`：從零起算的頁面索引。	不會隱式剖析。	`PdfObject`	`PdfParseException`：當不存在或超出範圍時。	匯入器預設使用第 `0` 頁。
`PdfReader::getPageContentStream(PdfObject $page)`	`page`：已剖析的頁面物件。	解析內容 stream。	`string`	`PdfParseException`：當 stream 無效時。	空的 stream 會導致匯入器失敗。
`PdfReader::getPageResources(PdfObject $page)`	`page`：已剖析的頁面物件。	解析頁面資源。	`array`	`PdfParseException`：當資源無效時。	資源字典會與 form 物件一併嵌入。
`PdfReader::getPageMediaBox(PdfObject $page)`	`page`：已剖析的頁面物件。	缺少時退回類似 A4 的尺寸。	`array`	剖析失敗。	回傳 PDF 空間座標。
`PdfReader::resolveRef(mixed $value)`	已剖析的值。	在適用情況下遞迴解析物件參照。	`mixed`	`PdfParseException`：當參照無效時。	為匯入流程對外開放的內部風格輔助方法。
`PdfReader::collectPageResources(PdfObject $page)`	`page`：已剖析的頁面物件。	走訪頁面資源的參照。	`array`	剖析失敗。	用於把相依物件與匯入的頁面一併嵌入。
`PdfReader::getRevisionCount()`	無。	計算已剖析的增量修訂數量。	`int`	剖析後預期不會發生。	對已簽章或經增量更新的 PDF 很有用。
`PdfReader::getRevisionXRef(int $index)`	從零起算的修訂索引。	回傳單一修訂的 xref 表。	`RevisionXRefTable`	`PdfParseException`：當索引無效時。	用於底層的修訂診斷。
`PdfReader::getRevisions()`	無。	回傳所有已剖析的修訂 xref 表。	`array`	剖析後預期不會發生。	唯讀的剖析器狀態檢視。
`PageImporter::import(PdfReader $reader, int $pageIndex = 0)`	已剖析的 reader 與從零起算的頁面索引。	省略時匯入第一頁。	`ImportedFormXObject`	`PdfParseException`：當無法擷取頁面時。	蒐集內容 stream、media box、資源，以及被參照的物件。

剖析器支援物件

這些是剖析器會回傳或在內部使用的值物件與輔助類別；當你要檢視匯入的物件、資源、stream 或修訂表時就會用到。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`new ImportedFormXObject(string $contentStream, array $mediaBox, array $embeddedObjects, array $resourcesDict)`	已解碼的內容 stream、media box、嵌入物件，以及資源字典。	儲存一份自含完整的匯入 form 內容。	`ImportedFormXObject`	預期不會發生。	通常由 `PageImporter::import()` 回傳。
`ImportedFormXObject::getWidth()`	無。	回傳匯入 form 的寬度（以點為單位）。	`float`	預期不會發生。	把 Chrome 輸出放進頁面時使用。
`ImportedFormXObject::getHeight()`	無。	回傳匯入 form 的高度（以點為單位）。	`float`	預期不會發生。	自動高度的算繪結果會透過這個值傳遞。
`ImportedFormXObject::getEmbeddedObjects()`	無。	回傳匯入 form 所需的物件。	`array`	預期不會發生。	寫出端的程式碼會用這些物件來保留資源。
`ImportedFormXObject::getResourcesDict()`	無。	回傳匯入的資源字典。	`array`	預期不會發生。	建構 form XObject 時使用。
`ImportedFormXObject::getMediaBox()`	無。	回傳匯入的 media box。	`array`	預期不會發生。	用於擺放位置的診斷。
`ImportedFormXObject::getContentStream()`	無。	回傳匯入頁面的內容 stream。	`string`	預期不會發生。	供 writer/import 整合使用。
`new PdfObject(int $objectNumber, int $generation, array $dictionary, ?string $rawStreamData = null, ?string $decodedStreamData = null, ?string $rawDictionaryBytes = null)`	物件編號、世代、已剖析的字典、選用的 stream 位元組、選用的已解碼 stream，以及選用的原始字典位元組。	儲存已剖析的物件狀態。	`PdfObject`	預期不會發生。	由剖析器內部建立。
`PdfObject::getRawDictionaryBytes()`	無。	在可取得時回傳原始字典位元組。	`string	null`	預期不會發生。
`PdfObject::getRawStreamData()`	無。	在可取得時回傳未解碼的 stream 位元組。	`string	null`	預期不會發生。
`PdfObject::getDictionary()`	無。	回傳已剖析的字典項目。	`array`	預期不會發生。	唯讀的剖析器檢視。
`PdfObject::get(string $key)`	字典鍵。	當鍵不存在時，回傳 `null`。	`mixed`	預期不會發生。	讓呼叫端不必自行剖析原始字典。
`PdfObject::getRef(string $key)`	字典鍵。	當值是參照時，回傳物件參照的 tuple。	`array	null`	預期不會發生。
`PdfObject::getArray(string $key)`	字典鍵。	回傳陣列值，無法取得時回傳空陣列。	`array`	預期不會發生。	針對字典陣列值的便利封裝。
`PdfObject::hasStream()`	無。	檢查是否存在 stream 位元組。	`bool`	預期不會發生。	用來辨別僅含字典的物件。
`PdfObject::getType()`	無。	讀取 `/Type`。	`string	null`	預期不會發生。
`PdfObject::getSubtype()`	無。	讀取 `/Subtype`。	`string	null`	預期不會發生。
`RevisionExtractor::extractRevision(string $pdfData, PdfReader $reader, int $revision)`	PDF 位元組、一個已剖析的 reader，以及從零起算的修訂索引。	擷取單一增量修訂。	`string`	`PdfParseException`：當邊界無效時。	供剖析器測試與診斷使用。
`RevisionExtractor::getRevisionBoundaries(string $pdfData, PdfReader $reader)`	PDF 位元組與一個已剖析的 reader。	找出各增量修訂的位元組範圍。	`array`	`PdfParseException`：當 xref 結構格式錯誤時。	有助於分析已簽章或經增量更新的 PDF。
串流解碼器 `StreamDecoder::decode(string $data, string	array $filter)`（解碼方法）	stream 位元組與一個或多個 PDF 篩選器。	依序套用篩選器。	`string`	`PdfParseException`：當篩選器不受支援或無效時。
`new ResourceCollector(PdfReader $reader)`	已剖析的 reader。	以空的已蒐集物件集合開始。	`ResourceCollector`	預期不會發生。	由 `PdfReader::collectPageResources()` 使用。
`ResourceCollector::traverse(mixed $value, int $depth = 0)`	已剖析的值與遞迴深度。	走訪資源參照，直到內部深度上限為止。	`void`	參照無效時的剖析失敗。	用於頁面匯入資源閉包的內部輔助方法。
`ResourceCollector::getCollected()`	無。	回傳已蒐集的資源物件。	`array`	預期不會發生。	在 `traverse()` 之後呼叫。
`new RevisionXRefTable(int $index, int $xrefOffset, array $xrefEntries, array $trailer, ?int $prevOffset)`	修訂索引、xref 偏移量、xref 項目、trailer，以及選用的前一個偏移量。	單一增量修訂的不可變快照。	`RevisionXRefTable`	預期不會發生。	由剖析器內部建立。
`RevisionXRefTable::getObjectNumbers()`	無。	回傳在該修訂表中有效的物件編號。	`array`	預期不會發生。	底層的修訂診斷 API。
`RevisionXRefTable::getActiveObjectCount()`	無。	計算有效物件的數量。	`int`	預期不會發生。	對剖析器的斷言很有用。
`RevisionXRefTable::hasRootUpdate()`	無。	回報該修訂是否更新了文件根節點。	`bool`	預期不會發生。	對增量更新分析很有用。
`RevisionXRefTable::getSize()`	無。	回傳 xref 表的大小值。	`int`	預期不會發生。	對應已剖析的 PDF xref 中繼資料。

底層的 tokenizer 與 xref API

只有在進行深入的剖析器診斷或縮減 fixture 時才需要這些 API；它們會曝露 PdfReader 底層的詞法器與交叉參照機制，一般匯入並不需要。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`new PdfTokenizer(string $data, int $offset = 0)`	PDF 位元組與選用的起始偏移量。	從偏移量零開始。	`PdfTokenizer`	預期不會發生。	底層的詞法剖析器。
`PdfTokenizer::getOffset()`	無。	回傳目前的位元組偏移量。	`int`	預期不會發生。	用於剖析器錯誤的診斷輔助方法。
`PdfTokenizer::setOffset(int $offset)`	位元組偏移量。	移動 tokenizer 的游標。	`void`	`PdfParseException`：當偏移量無效時。	請小心使用；剖析器狀態由呼叫端自行掌控。
`PdfTokenizer::isEof()`	無。	檢查游標是否已到達結尾。	`bool`	預期不會發生。	底層的剖析迴圈輔助方法。
`PdfTokenizer::skipWhitespace()`	無。	略過 PDF 空白與註解並前進。	`void`	預期不會發生。	在讀取 token 前使用。
`PdfTokenizer::readToken()`	無。	讀取下一個純量 token。	`string	int	float
`PdfTokenizer::readName()`	無。	讀取一個 PDF name 物件。	`string`	`PdfParseException`：當 name 格式錯誤時。	解碼 name 的跳脫序列。
`PdfTokenizer::readLiteralString()`	無。	讀取一個字面字串。	`string`	`PdfParseException`：當字串格式錯誤時。	處理巢狀括號與跳脫序列。
`PdfTokenizer::readHexString()`	無。	讀取一個十六進位字串。	`string`	`PdfParseException`：當十六進位格式錯誤時。	依剖析器規則為奇數長度的十六進位補位。
`PdfTokenizer::readNumber()`	無。	讀取一個整數或浮點數。	`int	float`	`PdfParseException`：當數字無效時。
`PdfTokenizer::readKeyword()`	無。	讀取一個 PDF 關鍵字。	`string`	`PdfParseException`：當關鍵字無效時。	集中處理關鍵字剖析。
`PdfTokenizer::readDictionary()`	無。	讀取一個 PDF 字典。	`array`	`PdfParseException`：當字典格式錯誤時。	用於物件、stream 與 trailer。
`PdfTokenizer::readArray()`	無。	讀取一個 PDF 陣列。	`array`	`PdfParseException`：當陣列格式錯誤時。	遞迴剖析輔助方法。
`PdfTokenizer::readValue()`	無。	讀取任何支援的 PDF 值。	`mixed`	`PdfParseException`：當值格式錯誤時。	常見的剖析基本操作。
`PdfTokenizer::readStreamData(int $length)`	stream 長度。	精確讀取要求的 stream 位元組。	`string`	`PdfParseException`：當 stream 邊界無效時。	在字典中的 stream 長度解析完成後使用。
`PdfTokenizer::peek(int $length = 1)`	位元組數量。	向前預讀但不移動游標。	`string`	預期不會發生。	對剖析器的分支判斷很有用。
`PdfTokenizer::searchBackward(string $pattern, int $startFrom = 0)`	比對樣式與選用的起始偏移量。	從結尾或指定偏移量往回搜尋。	`int	false`	預期不會發生。
`PdfTokenizer::readLine()`	無。	從目前偏移量讀取一行。	`string`	預期不會發生。	底層的掃描輔助方法。
`CrossRefParser::parseXRefTable(string $data, int $offset)`	PDF 位元組與 xref 表偏移量。	剖析傳統 xref 表的項目。	`array`	`PdfParseException`：當 xref 資料格式錯誤時。	底層的剖析器 API。
`CrossRefParser::parseXRefStream(string $data, int $offset)`	PDF 位元組與 xref stream 偏移量。	剖析 xref stream 的項目。	`array`	`PdfParseException`：當 stream 資料格式錯誤時。	支援現代 PDF 的 xref stream。

選用工廠與瀏覽器集區

EInvoiceServiceFactory 會延遲解析選用的 Premium 電子發票契約（缺少這些契約時回傳 null）。BrowserPool 是 renderer 自有的 Chrome 生命週期輔助類別；只有在長時間執行的 worker 中，你才需要直接管理它。

符號	參數	預設行為	回傳	拋出或失敗於	備註
`EInvoiceServiceFactory::makeEmbedder()`	無。	回傳 `null`，除非已安裝 Premium Pro 的電子發票支援。	嵌入器介面 `EmbedderInterface	null`	選用套件的建構錯誤。
`EInvoiceServiceFactory::makeValidator()`	無。	回傳 `null`，除非已安裝 Premium Enterprise 的驗證支援。	驗證器介面 `ValidatorInterface	null`	選用套件的建構錯誤。
`EInvoiceServiceFactory::makeDefaultProfile()`	無。	在可取得時回傳預設的電子發票設定檔。	設定檔介面 `ProfileInterface	null`	選用套件的錯誤。
`EInvoiceServiceFactory::makeSchematronRunner()`	無。	回傳 `null`，除非已安裝 Premium Enterprise 的 Schematron 支援。	Schematron 執行器介面 `SchematronRunnerInterface	null`	選用套件的建構錯誤。
`new BrowserPool(ChromeRendererConfig $config, ?LoggerInterface $logger = null)`	renderer 組態與選用的 logger。	瀏覽器會在首次呼叫 `getBrowser()` 時延遲啟動。	`BrowserPool`	在瀏覽器啟動前預期不會發生。	renderer 自有的生命週期輔助類別。
`BrowserPool::getBrowser()`	無。	啟動或回傳目前的 Chrome 瀏覽器實例。	`Browser`	瀏覽器啟動錯誤。	renderer 自有的生命週期輔助類別。
`BrowserPool::incrementRenderCount()`	無。	遞增算繪計數，並在集區政策要求時輪替。	`void`	瀏覽器生命週期錯誤。	供長時間執行的 worker 使用。
`BrowserPool::close()`	無。	關閉受管理的瀏覽器實例。	`void`	瀏覽器關閉錯誤。	在 worker 關閉時呼叫。

開發注意事項

這個 renderer 並不是用來隔離不受信任 HTML 的瀏覽器沙箱。算繪前必須先驗證大小、資源政策，以及呼叫端的授權。
剖析 API 刻意維持狹窄範圍。它們用於匯入 Chrome 輸出，並非用於一般 PDF 修復。
在長期存活的 worker 中，必須顯式關閉 renderer。