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/