NextPDF Symfony boot and discovery

At a glance

The kernel registers NextPdfBundle. The bundle’s Dependency Injection (DI) extension loads services.php and resolves the configuration tree into container parameters. One compiler pass then wires optional extensions and font warmup.

How Symfony Flex picks up the bundle

The bundle composer.json declares an auto-registration hint:

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

In a Symfony Flex application, this hint adds NextPDF\Symfony\NextPdfBundle to config/bundles.php for every environment (all). Without Flex, add the bundle manually in config/bundles.php. Symfony documents the bundle registration model at (https://symfony.com/doc/current/bundles.html). The bundle’s classes autoload under the PHP Standard Recommendation (PSR)-4 prefix NextPDF\Symfony\, mapped to src/Symfony/. A PSR-4 autoloader maps the namespace prefix to that base directory (PSR-4 §2).

Boot sequence

The boot sequence, verified against the bundle source:

1. Kernel registers bundles. Kernel::registerBundles() reads config/bundles.php and instantiates NextPDF\Symfony\NextPdfBundle, which extends Symfony\Component\HttpKernel\Bundle\Bundle.
2. Bundle build. NextPdfBundle::build() calls the parent method and then registers one compiler pass: OptionalExtensionPass. NextPdfBundle::getPath() returns the package root.
3. Extension load. The DI extension NextPDF\Symfony\DependencyInjection\NextPdfExtension (alias nextpdf) runs processConfiguration() against Configuration. It stores the resolved values as nextpdf.* container parameters, then loads config/services.php through a PhpFileLoader.
4. Required-extension guard. NextPdfExtension::load() finishes by asserting that ext-mbstring and ext-zlib are present, and fails fast if they are not.
5. Compiler pass runs. During container compilation, OptionalExtensionPass::process() configures extension availability flags on PdfFactory, conditionally registers the signer and time-stamping authority (TSA) client, and schedules font-registry warmup and lock.
6. Container compiled and cached. Symfony writes the compiled container. cache:warmup performs this step before traffic reaches the application.

Compiler passes

The bundle registers exactly one pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, in NextPdfBundle::build(). It runs in the default (before-optimization) pass group. The pass performs four steps. Each step is guarded, so it does nothing when its inputs are absent:

• Extension flags — adds setArtisanAvailable(...) and setProAvailable(...) method calls to the PdfFactory definition. The values come from compile-time class_exists probes for the Artisan browser factory and the Pro PDF/A class.
• Signer registration — registers a certificate-info factory and a signer service for the baseline B-B profile when nextpdf.signature is present, enabled is true, and a certificate is set.
• TSA client — registers a TSA client service when nextpdf.tsa has a Uniform Resource Locator (URL).
• Font warmup — adds warmup() and lock() method calls to the font-registry definition when nextpdf.preload_fonts is non-empty.

Container bindings

config/services.php defines the services. The document service nextpdf.document (aliased to NextPDF\Contracts\PdfDocumentInterface and NextPDF\Core\Document) is non-shared: each resolution returns a fresh document. PSR-11 explicitly permits this behavior; successive get() calls for one id may return different values (PSR-11 §1.1.2). The font registry is shared and locked after warmup. The image registry is shared and tagged kernel.reset. The full table is in /integrations/symfony/configuration/.

Configuration resolution order

1. Built-in defaults from Configuration (getConfigTreeBuilder()).
2. Application overrides in config/packages/nextpdf.yaml, plus environment overrides under config/packages/<env>/.
3. Symfony resolves %kernel.*% parameter placeholders. For example, fonts_path defaults to %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() writes the merged result to nextpdf.* container parameters that services.php and the compiler pass consume.

Invalid values fail at step 1–2 with a Symfony InvalidConfigurationException.

Diagnostics

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

The first command lists the registered services. The second prints the merged configuration. The third rebuilds the container and re-runs the compile-time extension probes.

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 (corpus manifest, retrieval transport) lives in _sidecars/rag-citations.yaml.

Spec	Clause	reference_id	Claim
PSR-11	psr_11_container#1.1.2.p3.b		Container resolution may differ per call
PSR-4	psr_4_autoload#x1.x2.p5		Namespace-prefix to base-directory mapping

See also

• /integrations/symfony/integration/ — end-to-end wiring reference.
• /integrations/symfony/install/ — installation and registration.
• /integrations/symfony/configuration/ — full configuration tree and service table.
• /integrations/symfony/overview/ — capability summary.