Symfony API 参考

概览

Symfony 包对外提供 bundle 注册、配置树、用于创建全新文档的可注入工厂、HTTP 响应辅助类，以及用于异步生成的 Messenger 类型。几乎所有应用代码只会接触两个符号：你注入的 PdfFactory 服务，用于构建 Document；以及将该文档转换为安全 HTTP 响应的 PdfResponse 辅助类。其余符号（bundle、扩展、编译器通道、配置树、Messenger DTO 与处理器）属于接线代码，你只需配置一次，或交由 Framework（框架）为你管理。

从这里开始： 如果你是新手，请注入 NextPDF\Symfony\Service\PdfFactory，调用 create() 获取一个全新的 Document，然后用 NextPDF\Symfony\Http\PdfResponse::download() 返回它。下面的第一个示例就是这样做的。

常见任务

下面是针对最常见任务的三段可运行代码片段。每段都只使用后续表格中记录的已验证符号。

从控制器返回 PDF 下载——注入工厂、构建文档，然后将其交给响应辅助类：

<?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 InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

它的作用：PdfFactory::create() 返回一个全新且已预配置的 Document。PdfResponse::download() 会以 Content-Type: application/pdf、attachment 处置方式以及该 bundle 固定的安全标头发送它。

流式输出大型 PDF 以保持较低的峰值内存——换用相应辅助类，返回一个 StreamedResponse：

<?php

declare(strict_types=1);

namespace App\Controller;

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

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

它的作用：PdfResponse::streamDownload() 会分块发出已实体化的 PDF，并省略 Content-Length；如需等价的内联行为，请使用 streamInline()。

派发 PDF 进行异步生成——向 Messenger 传输发送一个 GeneratePdfMessage，让渲染在工作进程上运行：

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

它的作用：该 DTO 携带一个构建器类字符串和一个经过校验的输出路径。处理器会解析构建器、构建文档，并在工作进程上保存它。该构建器类实现 PdfBuilderInterface，并注册在服务定位器中（关于定位器和工作进程接线，请参阅 Symfony 快速入门）。

工厂

当你需要了解这个用于创建全新文档的可注入服务的确切构造函数和 create() 契约时，请查阅此表。

符号	参数	默认行为	返回值	抛出或失败于	备注
`new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)`	`factory`：核心工厂；`defaults`：创建者、作者、语言、边距；`pdfa`：可选的 PDF/A 配置文件；`artisanConfig`：可选的 Chrome renderer（渲染器）配置。	默认值只会在配置后应用。	`PdfFactory`	容器接线错误。	该服务可以是单例，因为 `create()` 返回的是一个全新的文档。
`PdfFactory::create()`	无。	应用创建者和语言；仅当作者非空时应用作者；仅当可用时应用 PDF/A 和 Artisan 配置。	`NextPDF\Core\Document`	核心配置错误。	每个请求、命令或消息使用一次。
`PdfFactory::setArtisanAvailable(bool $available)`	`available`：编译期可用性标志。	在编译器通道启用它之前，该功能处于禁用状态。	`void`	预期为无。	由可选扩展编译器通道调用的内部钩子。
`PdfFactory::setProAvailable(bool $available)`	`available`：编译期可用性标志。	在编译器通道启用它之前，该功能处于禁用状态。	`void`	预期为无。	用于 Premium 可用性的内部钩子。

Bundle、扩展与配置

此表覆盖接线层——当你注册 bundle、解析 nextpdf 配置树，或追踪可选扩展检测时，请查阅它。第二个表格列出了配置键本身。

符号	参数	默认行为	返回值	抛出或失败于	备注
`NextPdfBundle::build(ContainerBuilder $container)`	Symfony 容器构建器。	调用父类的 build 方法并注册 `OptionalExtensionPass`。	`void`	编译器通道注册错误。	启用可选的 Artisan 和 Premium 功能检测。
`NextPdfBundle::getPath()`	无。	返回包的根路径。	`string`	预期为无。	由 Symfony bundle 发现和资源加载使用。
`NextPdfExtension::load(array $configs, ContainerBuilder $container)`	用户配置数组和容器构建器。	处理 `nextpdf` 配置，存储已解析的参数，加载服务定义，然后检查所需扩展。	`void`	配置校验、服务加载或缺失扩展错误。	所需扩展为 `mbstring` 和 `zlib`。
`NextPdfExtension::getAlias()`	无。	使用 `nextpdf` 作为根配置键。	`string`	预期为无。	在 `nextpdf:` 下配置该 bundle。
`Configuration::getConfigTreeBuilder()`	无。	定义经过校验的 `nextpdf` 配置树。	`TreeBuilder`	Symfony 配置定义错误。	在可行时与 Laravel 配置结构保持一致。
`OptionalExtensionPass::process(ContainerBuilder $container)`	Symfony 容器构建器。	检测可选的 Artisan 和 Premium 服务，并切换工厂的可用性标志。	`void`	编译器通道接线错误。	在容器编译期间运行。

配置键	类型	默认行为	备注
`page_format`	枚举	`A4`；允许的值包括 `A3`、`A5`、`Letter`、`Legal` 和 `Tabloid`。	应用于默认文档创建。
`orientation`	枚举	`P`；允许的值为 `P` 和 `L`。	当某个页面需要不同方向时，请使用显式的文档调用。
`unit`	枚举	`mm`；允许的值为 `pt`、`mm`、`cm` 和 `in`。	使框架默认值与核心单位保持一致。
`pdfa`	`string	null`	`null`；允许的值为 `4`、`4e` 和 `4f`。
`fonts_path` / `cache_path`	`string`	项目字体路径和内核缓存路径。	根据运行时角色，保持这两个路径可读或可写。
`signature.*`	`array`	默认禁用，签名级别为 `B-B`。	提供证书、密钥、密码、额外证书以及级别。
`tsa.*`	`array`	当 URL 为 `null` 时禁用；超时默认为 30 秒。	支持凭据、mTLS 文件、公钥固定以及 HTTP 策略。
`ocsp_cache.*`	`array`	启用，TTL 为 86400 秒。	在可用时由校验和长期签名流程使用。
`messenger.*`	`array`	传输 `async`，超时 120，重试 3 次。	由异步生成工作流使用。
`artisan.*`	`array`	除非已配置并安装，否则 Chrome 渲染器处于禁用状态。	当可选渲染器可用时，映射到 `ChromeRendererConfig`。
`defaults.*`	`array`	创建者 `NextPDF`，作者为空，语言 `en`，默认边距和字体。	由 `PdfFactory::create()` 应用。

HTTP 响应

使用此表选择合适的响应辅助类——内联显示还是下载、缓冲还是流式——并查看每个辅助类的文件名和标头行为。

符号	参数	默认行为	返回值	抛出或失败于	备注
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`：已构建的文档；`filename`：响应文件名。	缺失时添加 `.pdf`。	`Symfony\Component\HttpFoundation\Response`	核心序列化错误。	设置 PDF 内容类型和防御性标头。
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	与 `inline` 相同；处置方式为 attachment。	浏览器下载响应。	`Response`	与 `inline` 相同。	用于显式下载。
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	与 `inline` 相同。	分块发出已实体化的 PDF 字节。	`StreamedResponse`	与 `inline` 相同。	不能避免文档实体化。
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	与 `streamInline` 相同；处置方式为 attachment。	下载流响应。	`StreamedResponse`	与 `streamInline` 相同。	在渲染前应用输出大小策略。

Messenger 消息组件

当你构建异步路径时，请查阅此表——其中包括你派发的消息 DTO、你实现的构建器接口，以及在工作进程上运行的处理器。

符号	参数	默认行为	返回值	抛出或失败于	备注
`new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])`	`builderClass`：实现 `PdfBuilderInterface` 的类字符串；`outputPath`：目标 `.pdf`；`builderContext`：可序列化数据。	空的上下文数组。	消息 DTO。	`InvalidArgumentException`：用于无效的 FQCN、流包装器、空字节、路径遍历、空路径或非 `.pdf` 的目标。	Messenger 传输承载数据，而非闭包。
`PdfBuilderInterface::build(Document $document, array $context): Document`	`document`：全新且已配置的文档；`context`：可序列化的消息数据。	除消息值外没有默认上下文。	已配置的 `Document`。	构建器特定的异常。	使构建器保持确定性和幂等性。
`new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)`	PDF 工厂和带标签的构建器服务定位器。	在构造期间不会创建任何文档。	`GeneratePdfHandler`	容器接线错误。	定位器应只暴露 `PdfBuilderInterface` 的实现。
`GeneratePdfHandler::__invoke(GeneratePdfMessage $message)`	`message`：已校验的消息 DTO。	从容器中解析构建器、构建文档并保存它。	`void`	缺失构建器服务、无效的构建器结果、核心写入错误。	优先使用服务构建器，而非静态回调。

开发备注

不要将 Document 存储为服务。存储 PdfFactory，并为每个工作单元调用 create()。
仅将可序列化的上下文入队。不要将打开的流、闭包或请求对象放入 builderContext。
当部署具有租户专属存储根目录的系统时，请让输出路径策略比 DTO 更严格。