NextPDF Symfony integration overview

At a glance

nextpdf/symfony is the official Symfony 7 bundle for the NextPDF engine. It connects the engine to the Symfony container and gives you a document factory to inject into your own services. It also includes Hypertext Transfer Protocol (HTTP) response helpers and a path for generating Portable Document Format (PDF) files asynchronously, so work can run in the background.

What the bundle provides

NextPDF Symfony binds the nextpdf/core engine into a Symfony application as a standard bundle. It adds these building blocks, each verified against the bundle source in src/Symfony/:

A bundle entry point — NextPDF\Symfony\NextPdfBundle extends the Symfony Bundle base class and registers one compiler pass.
A dependency-injection extension — NextPDF\Symfony\DependencyInjection\NextPdfExtension loads the service definitions, turns the configuration tree into container parameters, and exposes the configuration alias nextpdf.
A typed configuration tree — NextPDF\Symfony\DependencyInjection\Configuration defines the nextpdf configuration schema. It validates enum values, sets defaults, and uses %kernel.*% parameter placeholders.
An injectable document factory — NextPDF\Symfony\Service\PdfFactory produces fresh, pre-configured NextPDF\Core\Document instances. It is the Symfony equivalent of a static facade.
HTTP response helpers — NextPDF\Symfony\Http\PdfResponse builds inline, download, and streamed responses with a fixed set of Open Worldwide Application Security Project (OWASP)-aligned security headers.
An asynchronous generation path — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler, and NextPDF\Symfony\Message\PdfBuilderInterface integrate with Symfony Messenger so PDF rendering can run on a worker.
A compile-time extension detector — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass detects optional NextPDF extensions and registers their services only when those extensions are present.

Container contract

The bundle registers a small, stable set of public container services. The document service nextpdf.document (aliased to NextPDF\Contracts\PdfDocumentInterface and NextPDF\Core\Document) is not shared: each resolution returns a distinct, disposable document. This matches the PHP Standard Recommendation 11 (PSR-11) container contract: two successive get() calls with the same identifier may return different values depending on the container’s configuration — see PSR-11 §1.1.2. The non-shared binding is deliberate. A document accumulates per-render state, so a fresh instance per request prevents state from leaking across requests in long-running workers.

The font registry (NextPDF\Contracts\FontRegistryInterface) works the other way: it is a shared singleton. The image registry carries the kernel.reset tag, so its bounded cache clears between requests under FrankenPHP and Messenger workers. The configuration page documents the full service and alias table.

Optional logging

The font and image registries accept an optional PHP Standard Recommendation 3 (PSR-3) logger. The bundle binds Psr\Log\LoggerInterface only when the application provides one (nullOnInvalid()). Logging is therefore an optional collaborator, not a hard dependency. This is consistent with the PSR-3 logger contract, where a logger is an injected, swappable collaborator (PSR-3).

Core versus optional capabilities

The bundle itself is Apache-2.0 core software. A few capabilities appear only when you install an optional package alongside the bundle:

Capability	Requires	Detection
PDF generation, `PdfFactory`, `PdfResponse`	core only	always available
Asynchronous generation	`symfony/messenger`	handler activates when Messenger is installed
Chrome DevTools Protocol (CDP) HTML rendering	`nextpdf/artisan`	compile-time `class_exists` probe
PDF/A archival, digital signatures	`nextpdf/premium` (installs Pro)	compile-time `class_exists` probe

When nextpdf/premium is installed, the bundle can apply a baseline PDF Advanced Electronic Signatures (PAdES) B-B signature configuration. Higher signature profiles are out of scope for this bundle’s documentation. For the edition matrix, see the NextPDF Premium documentation.

When to use this bundle

Use nextpdf/symfony when you build PDFs inside a Symfony 7 HTTP application or worker. The bundle gives you container-managed services, worker-safe registries, and secure download responses, so you do not have to wire the engine by hand. If you only need one-off generation in a script, the core nextpdf/core package alone is enough.

Conformance

Each row is a normative claim made on this page and pinned to a full 64-hex reference_id from the gated standards development organization (SDO) corpus. Provenance (corpus manifest, retrieval transport) is in _sidecars/rag-citations.yaml.

Spec	Clause	reference_id	Claim
PSR-11	`psr_11_container#1.1.2.p3.b`		Container get() return-value contract
PSR-3	`psr_3_logger#x3.p17`		LoggerInterface optional dependency

Commercial context

Digital signatures and PDF/A archival become available when nextpdf/premium (Pro) is installed alongside the bundle. This optional Pro capability requires no code change in the Core bundle documented here. See </get-license/?intent=symfony-pro>.