Install the NextPDF Symfony bundle

At a glance

Install the bundle with Composer. If your application uses Symfony Flex, the bundle registers itself. Without Flex, register it once in config/bundles.php.

Requirements

The bundle composer.json defines these constraints.

Dependency	Constraint
`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`

The bundle also checks two PHP extensions at container build time: ext-mbstring and ext-zlib. Every supported PHP runtime enables both. If either extension is absent, the guard fails fast with a clear message.

Optional packages

The bundle composer.json declares these packages under suggest. Add them when you need the behavior they provide:

Package	Adds
`nextpdf/artisan`	Chrome CDP HTML rendering, auto-detected at compile time
`nextpdf/premium`	PDF/A archival and digital signing (installs the Pro tier), auto-detected at compile time
`symfony/messenger`	Asynchronous PDF generation via the Messenger handler

Install with Composer

composer require nextpdf/symfony

The bundle autoloads under the PHP Standard Recommendation 4 (PSR-4) prefix NextPDF\Symfony\, mapped to src/Symfony/. This mapping is declared in composer.jsonautoload.psr-4. Composer’s generated autoloader maps the namespace prefix to that base directory, as PSR-4 §2 defines.

Register the bundle

Symfony Flex (recommended)

The bundle ships an auto-registration hint inside composer.json:

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

In a Flex-enabled application, this entry adds the bundle to config/bundles.php for every environment (all). You do not need to edit the file by hand. For the registration model, see the official Symfony bundle documentation (https://symfony.com/doc/current/bundles.html).

Manual registration (no Flex)

If your application does not use Symfony Flex, add the bundle to config/bundles.php yourself:

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

The bundle class is NextPDF\Symfony\NextPdfBundle. It extends the Symfony Symfony\Component\HttpKernel\Bundle\Bundle base class. The bundle’s getPath() method returns the package root. Its build() method registers the OptionalExtensionPass compiler pass.

Provide the configuration file

The bundle’s configuration alias is nextpdf. Create config/packages/nextpdf.yaml. When published, a Flex recipe adds a default copy here for you. A minimal file that relies entirely on built-in defaults looks like this:

nextpdf: ~

Every key has a default, so an empty configuration is valid. The /integrations/symfony/configuration/ page documents the full configuration tree.

Verify the installation

Confirm that the container can see the bundle services:

php bin/console debug:container nextpdf

You should see services that include the nextpdf.document alias and NextPDF\Symfony\Service\PdfFactory. To inspect the resolved configuration, run:

php bin/console debug:config nextpdf

This prints the merged configuration tree: your overrides plus the defaults.

Edge cases and gotchas

Core constraint span — the bundle accepts nextpdf/core^3.0 || ^5.2. Composer resolves the version that satisfies the rest of your dependency graph. Pin a single major version in your application’s composer.json if you need a deterministic engine version.
Missing extension guard — if php bin/console fails at boot with a message about ext-mbstring or ext-zlib, enable the named extension in php.ini. This fail-fast behavior is intentional, not a bundle defect.
Flex did not register the bundle — clear the Composer cache and reinstall. If you do not use Flex, use the manual config/bundles.php step.

Conformance

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

Spec	Clause	reference_id	Claim
PSR-4	`psr_4_autoload#x1.x2.p5`		Autoloader namespace-prefix to directory mapping