NextPDF Artisan 整合

概觀

nextpdf/artisan 是一個函式庫，不是 Framework（框架）外掛。若要整合它，請先安裝，再將一個 ChromeRendererConfig 掛到 NextPDF 文件上，然後呼叫 writeHtmlChrome()。本頁概述 Artisan 其餘文件涵蓋的內容。

安裝

composer require nextpdf/artisan

完整需求矩陣與外部 Chrome 相依套件請見：/integrations/artisan/install/.

啟動與探索

Artisan 不提供任何 service provider（服務供應器）、bundle（套件），也沒有 framework 自動探索資訊清單。它是一個單純的 PSR-4 函式庫（NextPDF\Artisan\、NextPDF\Parser\），由你直接取用；沒有需要「探索」的項目。進入點是 writeHtmlChrome() 方法；一旦橋接類別可被自動載入，nextpdf/core 就會在 Document 上公開這個方法。關於探索與啟動模型，請見 /integrations/artisan/boot-and-discovery/.

容器繫結

無須發布任何容器整合。在沒有 DI 容器的環境中，EInvoiceServiceFactory 提供靜態工廠方法（makeEmbedder、makeValidator、makeDefaultProfile、makeSchematronRunner）。這些方法會回傳 Premium e-invoice 合約實作，或在未安裝 Premium 層時回傳 null。這與各 framework 包裝套件回傳 null 的行為一致，讓沒有容器的程式碼也能取得一致的介面。詳細說明與設計理由，請見 /integrations/artisan/boot-and-discovery/.

公開 API 進入點

進入點	位置	文件說明於
Document::writeHtmlChrome()（核心方法）	nextpdf/core	快速開始 /integrations/artisan/quickstart/
Document::setChromeRendererConfig()（核心方法）	nextpdf/core	快速開始 /integrations/artisan/quickstart/
ChromeHtmlRenderer::render()	nextpdf/artisan	正式環境用法 /integrations/artisan/production-usage/
ChromeRendererConfig / ::fromArray()	nextpdf/artisan	組態設定 /integrations/artisan/configuration/
EInvoiceServiceFactory::make*()	nextpdf/artisan	啟動與探索 /integrations/artisan/boot-and-discovery/

上述 writeHtmlChrome() 的簽章為 (string $html, ?float $width = null, ?float $height = null): static，已對照 nextpdf/coresrc/Core/Concerns/HasTextOutput.php 驗證。

煙霧測試

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());
assert($renderer->getHtmlSecurityPolicy()->getName() === 'default');
echo "ARTISAN_WIRED\n";

這證明自動載入與 nextpdf/core 合約繫結能在不啟動 Chrome 的情況下完成 resolve（解析）（此行為由 tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected 斷言）。實際操作 Chrome 的端對端渲染煙霧測試，請見 /integrations/artisan/chrome-renderer-setup/.

後續步驟

• 渲染你的第一份文件：/integrations/artisan/quickstart/
• 所有組態選項：/integrations/artisan/configuration/
• 佈建 Chrome/容器：/integrations/artisan/chrome-renderer-setup/
• 傳輸與隔離模型：/integrations/artisan/security-and-operations/
• 正式環境接線與批次 worker：/integrations/artisan/production-usage/
• 故障診斷：/integrations/artisan/troubleshooting/
• 套件如何啟動：/integrations/artisan/boot-and-discovery/

商業脈絡

此橋接層是功能完整的開放原始碼。Premium 層則會在已渲染的 PDF 之上，再加入 e-invoice 內嵌（Pro）與驗證（Enterprise）。當這些層不存在時，EInvoiceServiceFactory 會降級為回傳 null，因此你只要寫一次整合程式碼，無論有沒有 Premium 都能執行。

另請參閱

• 總覽 /integrations/artisan/overview/
• 安裝 /integrations/artisan/install/
• 啟動與探索 /integrations/artisan/boot-and-discovery/
• 快速開始 /integrations/artisan/quickstart/