NextPDF Symfony 集成概览
快速概览
标题为“快速概览”的章节nextpdf/symfony 是 NextPDF 引擎的官方 Symfony 7 bundle。它将引擎接入 Symfony container（容器），并提供一个可注入到你自己的服务中的文档 factory（工厂）。它还附带 HTTP response 辅助工具，以及一条异步生成 PDF 的路径，让生成工作能在后台运行。
bundle 提供什么
标题为“bundle 提供什么”的章节NextPDF Symfony 以标准 bundle 的形式将 nextpdf/core 引擎接入 Symfony 应用程序。它提供以下构建块，每一项都已对照 src/Symfony/ 中的 bundle 源码逐一验证：
- 一个 bundle 入口点 —
NextPDF\Symfony\NextPdfBundle继承 Symfony 的Bundle基类，并注册一个 compiler pass。 - 一个依赖注入 extension —
NextPDF\Symfony\DependencyInjection\NextPdfExtension加载服务定义，将 config tree（配置树）转换为 container 参数，并对外公开配置别名nextpdf。 - 一棵类型化配置树 —
NextPDF\Symfony\DependencyInjection\Configuration定义了nextpdf的配置 schema。这个 schema 会校验 enum 值、设置默认值，并使用%kernel.*%参数 placeholder（占位符）。 - 一个可注入的文档 factory —
NextPDF\Symfony\Service\PdfFactory会创建全新、预先配置好的NextPDF\Core\Document实例。它相当于静态 facade 的 Symfony 版本。 - HTTP response 辅助工具 —
NextPDF\Symfony\Http\PdfResponse会构建 inline、下载与流式响应，并附带一组固定、符合 OWASP 原则的安全标头。 - 一条异步生成路径 —
NextPDF\Symfony\Message\GeneratePdfMessage、NextPDF\Symfony\Message\GeneratePdfHandler与NextPDF\Symfony\Message\PdfBuilderInterface会与 Symfony Messenger 集成，让 PDF 渲染能在 worker 上运行。 - 一个编译期 extension 检测器 —
NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass会检测可选的 NextPDF extension，并且只在这些 extension 存在时注册它们的服务。
容器契约
标题为“容器契约”的章节这个 bundle 会注册一组小而稳定的公开 container 服务。文档服务 nextpdf.document（别名为 NextPDF\Contracts\PdfDocumentInterface 与 NextPDF\Core\Document）并非共享：每次 resolve（解析）都会返回一份彼此独立、用完即弃的文档。这符合 PSR-11 容器契约：在该契约下，以相同标识符连续调用两次 get()，根据容器配置，可能返回不同的值 — 见 PSR-11 §1.1.2。非共享绑定是有意设计的：文档会累积每次渲染的状态，因此每个请求都会拿到全新实例，可避免状态在长时间运行的 worker 中跨请求泄漏。
字体注册表（NextPDF\Contracts\FontRegistryInterface）的运作方式则相反：它是共享的 singleton（单例）。图像注册表带有 kernel.reset 标签，因此在 FrankenPHP 与 Messenger worker 下，其有界缓存会在请求之间被清除。配置页面列出了完整的服务与别名对照表。
可选的日志记录
标题为“可选的日志记录”的章节字体与图像注册表都接受一个可选的 PSR-3 logger。只有在应用程序提供 logger 时，这个 bundle 才会绑定 Psr\Log\LoggerInterface（nullOnInvalid()）。因此，日志记录是可选的协作组件，而非硬性依赖。这与 PSR-3 logger 契约一致：在该契约下，logger 是一个可注入、可替换的协作组件（PSR-3）。
核心能力与可选能力
标题为“核心能力与可选能力”的章节这个 bundle 本身是 Apache-2.0 核心软件。少数能力只有在你同时安装相应可选包后才会出现：
| 能力 | 需要 | 检测方式 |
|---|---|---|
PDF 生成、PdfFactory、PdfResponse | 仅需核心 | 始终可用 |
| 异步生成 | symfony/messenger | 安装 Messenger 后 handler 即启用 |
| Chrome CDP HTML 渲染 | nextpdf/artisan | 编译期 class_exists 探测 |
| PDF/A 归档、数字签名 | nextpdf/premium（安装 Pro） | 编译期 class_exists 探测 |
安装 nextpdf/premium 后，这个 bundle 可应用一组基线 PAdES B-B 签名配置。更高级的签名配置不在这个 bundle 的文档范围内。关于版本对照矩阵，请参阅 NextPDF Premium 文档。
何时使用这个 bundle
标题为“何时使用这个 bundle”的章节当你在 Symfony 7 HTTP 应用程序或 worker 内构建 PDF 时，就使用 nextpdf/symfony。这个 bundle 为你提供由 container 管理的服务、worker 安全的注册表，以及安全的下载响应，因此你不必手动装配引擎。如果你只需要在脚本中做一次性生成，单靠核心包 nextpdf/core 就足够了。
符合性
标题为“符合性”的章节每一行都对应本页提出的一项规范性主张，并锚定到受管制 SDO 语料库中的完整 64 位十六进制 reference_id。Provenance（来源信息）（语料库 manifest、检索传输）记录在 _sidecars/rag-citations.yaml 中。
| 规范 | 条款 | 参考 ID | 主张 |
|---|---|---|---|
| PSR-11 | psr_11_container#1.1.2.p3.b | Container get() 返回值契约 | |
| PSR-3 | psr_3_logger#x3.p17 | LoggerInterface 可选依赖 |
商业背景
标题为“商业背景”的章节当 nextpdf/premium（Pro）与这个 bundle 一同安装时，数字签名与 PDF/A 归档即可使用。这是一项可选的 Pro 能力。这里所记载的 Core bundle 采用它时不需要任何代码变更。见 </get-license/?intent=symfony-pro>。
另请参阅
标题为“另请参阅”的章节- /integrations/symfony/install/ — 安装并注册这个 bundle。
- /integrations/symfony/configuration/ — 完整的
nextpdf配置树与服务对照表。 - /integrations/symfony/quickstart/ — 一个可运行的控制器与异步示例。
- /integrations/symfony/boot-and-discovery/ — Symfony 如何发现并启动这个 bundle。
- /integrations/symfony/production-usage/ — worker 安全性、流式与异步模式。