Configure the NextPDF Symfony bundle

At a glance

Configure all bundle behavior under the nextpdf root key in config/packages/nextpdf.yaml. Every key has a default, so you only set values you want to change. This page mirrors Configuration.php exactly.

Configuration tree

NextPDF\Symfony\DependencyInjection\Configuration defines the schema. Invalid values fail at container build time with a Symfony InvalidConfigurationException.

Top-level keys

Key	Type	Default	Validation
`page_format`	enum	`A4`	one of `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`
`orientation`	enum	`P`	one of `P`, `L`
`unit`	enum	`mm`	one of `pt`, `mm`, `cm`, `in`
`pdfa`	scalar	`null`	one of `null`, `4`, `4e`, `4f`
`fonts_path`	scalar	`%kernel.project_dir%/resources/fonts`	—
`cache_path`	scalar	`%kernel.cache_dir%/nextpdf`	—
`image_cache_mb`	integer	`50`	minimum `0`
`font_cache_locking`	boolean	`true`	—
`preload_fonts`	list of strings	`[]`	—

`icc_profile`

Key	Type	Default
`icc_profile.rgb`	scalar	`null`
`icc_profile.cmyk`	scalar	`null`

`defaults`

Applies to every document PdfFactory produces.

Key	Type	Default
`defaults.creator`	scalar	`NextPDF`
`defaults.author`	scalar	(empty)
`defaults.language`	scalar	`en`
`defaults.margin_top`	float	`10.0`
`defaults.margin_right`	float	`10.0`
`defaults.margin_bottom`	float	`10.0`
`defaults.margin_left`	float	`10.0`
`defaults.font_family`	scalar	`dejavusans`
`defaults.font_size`	float	`12.0`
`defaults.trim_box`	variable	`null`
`defaults.bleed_box`	variable	`null`

PdfFactory reads creator, author, and language from this section and applies them to each new document. The bundle stores the remaining keys as container parameters for engine use.

`artisan`

Applies only when nextpdf/artisan is installed and detected.

Key	Type	Default
`artisan.chrome_binary`	scalar	`null`
`artisan.render_timeout`	integer	`30`
`artisan.default_css`	scalar	(empty)
`artisan.no_sandbox`	boolean	`false`
`artisan.max_html_size`	integer	`5000000`

`signature`

Applies only when nextpdf/premium is installed. When the bundle and Pro tier are present, the supported signing configuration is the baseline B-B profile. The level node accepts the string values below for schema compatibility with the wider NextPDF configuration family. This bundle delivers B-B signing capability. Profiles beyond B-B are documented separately in the NextPDF Premium documentation and are not claimed here.

Key	Type	Default	Validation
`signature.enabled`	boolean	`false`	—
`signature.certificate`	scalar	`null`	—
`signature.private_key`	scalar	`null`	—
`signature.password`	scalar	(empty)	—
`signature.extra_certs`	list of strings	`[]`	—
`signature.level`	enum	`B-B`	accepted set: `B-B`, `B-T`, `B-LT`, `B-LTA` (B-B delivered; `B-T`/`B-LT`/`B-LTA` are schema-compatibility values, not delivered Pro capability)

The compiler pass registers a signer service only when signature.enabled is true and signature.certificate is set; otherwise, the section is inert.

`tsa`

Time Stamp Authority (TSA) client configuration, used by Pro signing when configured.

Key	Type	Default
`tsa.url`	scalar	`null`
`tsa.username`	scalar	(empty)
`tsa.password`	scalar	(empty)
`tsa.cert`	scalar	`null`
`tsa.key`	scalar	`null`
`tsa.timeout`	integer	`30`
`tsa.allow_insecure_http`	boolean	`false`
`tsa.pinned_public_keys`	list of strings	`[]`
`tsa.warn_on_key_rotation`	boolean	`true`

The bundle registers a TSA client service only when tsa.url is set.

`ocsp_cache`

Key	Type	Default
`ocsp_cache.enabled`	boolean	`true`
`ocsp_cache.ttl`	integer	`86400`
`ocsp_cache.directory`	scalar	`null`

`messenger`

Settings for asynchronous generation, consumed when symfony/messenger is installed.

Key	Type	Default
`messenger.transport`	scalar	`async`
`messenger.timeout`	integer	`120`
`messenger.retries`	integer	`3`

Reference configuration

A configuration file that shows every section with its defaults:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Container services and aliases

The bundle loads its service definitions from config/services.php. The table below mirrors that file exactly.

Service id	Shared	Public	Notes
`NextPDF\Typography\FontRegistry`	yes	—	constructed from `nextpdf.fonts_path`; optional PHP Standard Recommendation 3 (PSR-3) logger
`NextPDF\Contracts\FontRegistryInterface`	(alias)	yes	alias of `FontRegistry`
`NextPDF\Graphics\ImageRegistry`	yes	—	bounded least-recently-used (LRU); tagged `kernel.reset` (`reset`)
`NextPDF\Core\DocumentFactory`	yes	—	shares the two registries
`NextPDF\Contracts\DocumentFactoryInterface`	(alias)	yes	alias of `DocumentFactory`
`NextPDF\Symfony\Service\PdfFactory`	yes	yes	reads `defaults`, `pdfa`, and `artisan` parameters
`NextPDF\Contracts\PdfDocumentInterface`	no	yes	factory `[PdfFactory, create]`
`NextPDF\Core\Document`	(alias)	—	alias of `PdfDocumentInterface`
`nextpdf.document`	(alias)	yes	alias of `PdfDocumentInterface`
`NextPDF\Symfony\Http\PdfResponse`	—	yes	stateless helper

The bundle also registers EInvoice contract bindings (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) only when the corresponding Premium implementation classes exist. Each service is non-shared, so callers receive a fresh instance. Per-call parser state never leaks across requests.

Shared versus non-shared

nextpdf.document (and its aliases) is non-shared: every container resolution returns a distinct document. Under PHP Standard Recommendation 11 (PSR-11), a container may return a different value on successive get() calls with the same identifier; see PSR-11 §1.1.2. The font registry is shared and locked after warmup. Structural font data is parsed once per process and cannot be mutated mid-request.

The FontRegistry and ImageRegistry services accept an optional Psr\Log\LoggerInterface; Symfony binds it with nullOnInvalid(). The logger remains an optional, swappable collaborator, consistent with the PSR-3 logger contract.

Autowiring

PdfFactory, PdfResponse, the document factory interface, and the font registry interface are public. They can be fetched from the container or type-hinted in autowired controllers and services. Constructor injection of NextPDF\Symfony\Service\PdfFactory is the recommended entry point.

Edge cases and gotchas

pdfa set without Pro — the value is stored but ignored. PdfFactory applies Portable Document Format/Archival (PDF/A) only when the Pro extension is detected at compile time.
image_cache_mb: 0 — valid; disables the image LRU cache. Negative values are rejected at build time.
signature.enabled: true without signature.certificate — the signer service is not registered; the configuration is silently inert by design.
%kernel.*% placeholders — fonts_path and cache_path defaults use Symfony container parameters; override with absolute paths only when the literal path is required.

Conformance

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

Spec	Clause	reference_id	Claim
PSR-11	`psr_11_container#1.1.2.p3.b`		get() may return different values per resolution
PSR-3	`psr_3_logger#x3.p17`		Optional LoggerInterface collaborator

Commercial context

The signature and tsa sections apply only when nextpdf/premium (Pro) is installed. This optional Pro capability requires no code change in the Core bundle documented here. See </get-license/?intent=symfony-pro>.