NextPDF Symfony 集成

概览

安装 nextpdf/symfony，让 Flex 注册这个包（bundle）（也可以自行注册），添加 config/packages/nextpdf.yaml，然后注入 PdfFactory。本页是整个接线流程的索引，每个步骤都会链接到更深入的页面。

安装

composer require nextpdf/symfony

这个包需要 nextpdf/core^3.0 || ^5.2、symfony/*^7.2，以及 psr/log^3.0。类会通过 PSR-4 前缀 NextPDF\Symfony\ 自动加载，并映射到 src/Symfony/。PSR-4 自动加载器会将命名空间前缀解析到该基目录（PSR-4 §2）。完整需求与可选包，请见 /integrations/symfony/install/.

启动与自动发现

使用 Symfony Flex 时，包的 extra.symfony.bundles 项（位于 composer.json 中）会在所有环境中注册 NextPDF\Symfony\NextPdfBundle。如果没有使用 Flex，请自行将它添加到 config/bundles.php：

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

完整的启动顺序与 compiler pass 行为，请见 /integrations/symfony/boot-and-discovery/.

容器绑定

包的 config/services.php 文件会注册下列服务：

服务 / 别名	生命周期
`NextPDF\Symfony\Service\PdfFactory`	共享、public——注入这个
`nextpdf.document` → `PdfDocumentInterface` → `Document`	非共享、public——每次解析都产生新的
`NextPDF\Contracts\FontRegistryInterface`	共享、预热后锁定
`NextPDF\Graphics\ImageRegistry`	共享、`kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	共享
`NextPDF\Symfony\Http\PdfResponse`	public 的无状态辅助类

document 绑定被有意设为非共享。PSR-11 允许容器对同一个 id 连续调用 get() 时返回不同的值。每次都创建全新的 document，可以避免在长时间运行的 worker 中带入跨请求状态（PSR-11 §1.1.2）。完整的服务与别名表（包括条件式 EInvoice 绑定）请见 /integrations/symfony/configuration/.

发布配置

配置别名是 nextpdf。创建 config/packages/nextpdf.yaml。Flex recipe 发布后，会为你放置一份默认副本。每个键都有默认值，因此最精简的文件如下：

nextpdf: ~

完整的配置树见 /integrations/symfony/configuration/.

初次使用

注入 PdfFactory，然后通过 PdfResponse 返回结果：

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

端到端控制器与 Messenger 异步路径，请见 /integrations/symfony/quickstart/.

包冒烟测试

无需编写任何应用程序代码，即可确认接线是否正确：

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

debug:container nextpdf 应该会列出 PdfFactory、nextpdf.document 别名，以及各个 registry。lint:container 会验证每个服务参数都能解析。要测试生成功能，请添加上面的控制器，然后请求 /hello.pdf。

公开 API 入口点

应用程序代码支持使用以下公开符号：

符号	用途
`NextPDF\Symfony\Service\PdfFactory::create()`	全新且已预先配置的 `Document`
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	带安全标头的缓冲响应
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	分块流式（stream）响应
`NextPDF\Symfony\Message\GeneratePdfMessage`	异步生成用的 DTO（已验证）
`NextPDF\Symfony\Message\PdfBuilderInterface`	由 handler 解析的 builder 契约

符合性

每一行都是本页提出的一项规范性主张。每项主张都锁定到一个来自受管控 SDO 语料库的完整 64 位十六进制 reference_id。provenance（来源信息，包括语料库清单和检索传输）放在 _sidecars/rag-citations.yaml。

规范	条款	参考 ID	主张
PSR-11	`psr_11_container#1.1.2.p4`		容器的 has() / get() 标识符契约
PSR-4	`psr_4_autoload#x1.x2.p5`		自动加载器命名空间映射

另见

/integrations/symfony/install/ — 需求与注册。
/integrations/symfony/boot-and-discovery/ — 发现、启动、compiler pass。
/integrations/symfony/configuration/ — 完整模式与服务表。
/integrations/symfony/quickstart/ — 可运行的控制器与异步示例。
/integrations/symfony/production-usage/ — worker 安全性与流式处理。