安装 NextPDF Symfony bundle

概览

使用 Composer 安装 bundle。在启用 Symfony Flex 的应用中，bundle 会自动注册。未使用 Flex 时，你只需在 config/bundles.php 中注册一次即可。

需求条件

以下约束条件来自 bundle 的 composer.json。

依赖项	约束条件
php	>=8.4 <9.0
nextpdf/core	^3.0 || ^5.2
symfony/framework-bundle	^7.2
symfony/dependency-injection	^7.2
symfony/config	^7.2
symfony/http-foundation	^7.2
psr/log	^3.0

bundle 还会在容器构建时额外检查两个 PHP 扩展：ext-mbstring 与 ext-zlib。这两者在每个受支持的 PHP 运行时中都已启用。若其中一个缺失，该检查会快速失败，并给出清晰消息。

可选软件包

这些软件包在 bundle 的 composer.json 中以 suggest 声明。安装后会解锁额外行为：

软件包	新增功能
nextpdf/artisan	基于 Chrome CDP 的 HTML 渲染，编译期自动检测
nextpdf/premium	PDF/A 归档与数字签名（会安装 Pro 等级），编译期自动检测
symfony/messenger	通过 Messenger handler 异步生成 PDF

用 Composer 安装

composer require nextpdf/symfony

bundle 会通过 PSR-4 前缀 NextPDF\Symfony\ 自动加载，并映射到 src/Symfony/。这项映射在 composer.jsonautoload.psr-4 中声明。Composer 生成的自动加载器会按照 PSR-4 自动加载规范，将命名空间前缀映射到该基础目录；详见 PSR-4 §2。

注册 bundle

Symfony Flex（推荐）

bundle 在 composer.json 内附带一个自动注册提示：

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

在启用 Flex 的应用中，这项配置会把 bundle 添加到 config/bundles.php，并应用于每个环境（all）。你不需要手动编辑这个文件。关于这套注册模型，请参阅 Symfony 官方 bundle 文档（https://symfony.com/doc/current/bundles.html）。

手动注册（不使用 Flex）

如果应用未使用 Symfony Flex，请自行把 bundle 添加到 config/bundles.php：

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

bundle 类是 NextPDF\Symfony\NextPdfBundle。它继承自 Symfony 的 Symfony\Component\HttpKernel\Bundle\Bundle 基类。bundle 的 getPath() 会返回软件包根目录。它的 build() 方法会注册 OptionalExtensionPass 编译器 pass。

提供配置文件

bundle 的配置别名是 nextpdf。创建 config/packages/nextpdf.yaml。发布后，Flex recipe 会在这里为你放置一份默认副本。完全依赖内置默认值时，最小文件如下：

nextpdf: ~

每个键都有默认值，因此空配置也有效。完整配置树见 /integrations/symfony/configuration/。

验证安装

确认容器能看到 bundle 服务：

php bin/console debug:container nextpdf

你应该会看到包含 nextpdf.document 别名和 NextPDF\Symfony\Service\PdfFactory 的服务。若要查看解析后的配置，请运行：

php bin/console debug:config nextpdf

这会打印合并后的配置树，即你的覆盖值与默认值合并后的结果。

边界情况与陷阱

• Core 约束范围 —— bundle 接受 nextpdf/core^3.0 || ^5.2。 Composer 会解析出能够满足其余依赖关系图的版本。如果你需要确定性的引擎版本，请在应用的 composer.json 中固定到单一主版本。
• 缺失扩展检查 —— 如果 php bin/console 在启动时失败，并出现关于 ext-mbstring 或 ext-zlib 的消息，请在 php.ini 中启用对应扩展。这是刻意设计的快速失败行为，并非 bundle 缺陷。
• Flex 未注册 bundle —— 请清除 Composer 缓存后重新安装。如果你不使用 Flex，请改用上面的手动 config/bundles.php 步骤。

符合性

每一行都是本页提出的规范性主张，并锚定到受管 SDO 语料库中的一组完整 64 位十六进制 reference_id。来源（Provenance）信息位于 _sidecars/rag-citations.yaml。来源信息涵盖语料库清单与检索传输过程。

规范	条款	参考 ID（reference_id）	主张
PSR-4	psr_4_autoload#x1.x2.p5		自动加载器的命名空间前缀到目录的映射

另请参阅

• /integrations/symfony/overview/ —— bundle 提供的功能。
• /integrations/symfony/configuration/ —— 完整的配置树与服务表。
• /integrations/symfony/quickstart/ —— 第一个可运行的控制器。
• /integrations/symfony/boot-and-discovery/ —— 发现与启动顺序的深入说明。