Problemen met de NextPDF Symfony-bundle oplossen

In het kort

De meeste problemen vallen in een van deze vier gebieden: detectie, configuratievalidatie, containerbedrading of Messenger-routing. Elke sectie koppelt een symptoom aan het onderliggende gedrag van de bundle en geeft vervolgens een consolecommando waarmee u de oplossing kunt controleren.

De bundle is niet geregistreerd

Symptoom: u kunt PdfFactory niet autowiren, of debug:container nextpdf geeft niets terug.

Oorzaak: de bundle is niet toegevoegd aan config/bundles.php. Mogelijk is Flex niet uitgevoerd, of de applicatie gebruikt geen Flex.

Oplossen:

php bin/console debug:container nextpdf

Als de opdracht geen services teruggeeft, voeg de bundle dan handmatig toe:

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

De composer.json van de bundle bevat de hint voor automatische registratie onder extra.symfony.bundles. Deze geldt alleen voor applicaties met Flex ingeschakeld.

Het opstarten mislukt door een ontbrekende PHP-extensie

Symptoom: de kernel werpt bij het opstarten een RuntimeException die ext-mbstring of ext-zlib noemt.

Oorzaak: dit komt van NextPdfExtension::guardRequiredExtensions(), de bewuste fail-fast-controle van de bundle. Het is geen defect.

Oplossen: schakel de genoemde extensie in php.ini in en herstart vervolgens de runtime. Bevestig dit met:

php -m | grep -E 'mbstring|zlib'

De configuratie wordt tijdens de build geweigerd

Symptoom: Symfony werpt tijdens cache:clear of cache:warmup een Symfony\Component\Config\Definition\Exception\InvalidConfigurationException.

Oorzaak: een waarde valt buiten het schema. Configuration.php definieert de volgende beperkingen:

• page_format moet een van de volgende waarden zijn: A4, A3, A5, Letter, Legal, Tabloid.
• orientation moet P of L zijn.
• unit moet een van de volgende waarden zijn: pt, mm, cm, in.
• pdfa moet null, 4, 4e of 4f zijn.
• image_cache_mb moet >= 0 zijn.

Oplossen: toon de samengevoegde configuratie en corrigeer vervolgens de sleutel die de fout veroorzaakte:

php bin/console debug:config nextpdf

PDF/A of ondertekening heeft geen effect

Symptoom: pdfa of de sectie signature is ingesteld, maar de uitvoer blijft een gewoon Portable Document Format-bestand (PDF).

Oorzaak: deze mogelijkheden vereisen nextpdf/premium. Tijdens het compileren past PdfFactory PDF/A alleen toe wanneer de Pro-extensie wordt gedetecteerd. De compiler-pass registreert alleen een ondertekenaar wanneer signature.enabled true is en signature.certificate is ingesteld.

Oplossen: controleer of Premium is geïnstalleerd en of de ondertekenaarsservice bestaat:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Als Premium ontbreekt, slaat de bundle de configuratie op maar houdt die bewust inactief. Met Pro is de gedocumenteerde ondertekeningsmogelijkheid van de bundle het basisprofiel B-B. De documentatie van NextPDF Premium behandelt profielen die verder gaan dan B-B.

Chrome-weergave doet niets

Symptoom: de artisan-configuratie wordt genegeerd.

Oorzaak: weergave via het Chrome DevTools Protocol (CDP) vereist nextpdf/artisan. De compiler-pass detecteert die extensie tijdens het compileren met class_exists. Als de extensie ontbreekt, wordt de renderer niet bedraad.

Oplossen:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

De detectie vindt plaats tijdens het compileren van de container. Nadat u de extensie hebt geïnstalleerd, voert u opnieuw een cache:clear uit.

Messenger-handler wordt nooit aangeroepen

Symptoom: u dispatcht GeneratePdfMessage, maar er wordt geen PDF geschreven.

Oorzaken en oplossingen:

• Bericht niet gerouteerd — voeg een routeringsregel toe die NextPDF\Symfony\Message\GeneratePdfMessage toewijst aan een transport in config/packages/messenger.yaml, en start vervolgens een worker (php bin/console messenger:consume <transport>).
• Builder niet in de locator — de handler haalt de builder op uit een PHP Standards Recommendation 11-locator (PSR-11) aan de hand van de bijbehorende class-string-id. Een container-identifier is een tekenreeks die een vermelding uniek identificeert (PSR-11 §1.1.2). Als de locator de builder-klasse niet heeft geregistreerd, werpt de handler een RuntimeException met de melding dat de geconfigureerde builder PdfBuilderInterface moet implementeren. Registreer de builder en verwijs er vervolgens naar vanuit de locator.

Inspecteer de routering en de locator:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

Bericht bij dispatch geweigerd met InvalidArgumentException

Symptoom: het construeren van GeneratePdfMessage werpt een InvalidArgumentException.

Oorzaak: het data transfer object (DTO) van het bericht valideert zijn invoer. De gevalideerde afwijzingsregels zijn:

• een leeg uitvoerpad, of een pad dat een null-byte bevat;
• een stream-wrapper-schema (bijvoorbeeld php://...);
• een ..-segment voor path-traversal (met POSIX- of Windows-scheidingstekens);
• een uitvoerpad dat niet eindigt op .pdf (hoofdletterongevoelig);
• een builderClass die geen syntactisch geldige klassenaam is.

Oplossen: geef een absoluut bestandssysteempad op dat eindigt op .pdf en een echte, volledig gekwalificeerde builder-klassenaam.

Een document bevat verouderde gegevens

Symptoom: een gegenereerde PDF bevat inhoud van een eerder verzoek.

Oorzaak: een langlopende worker hield een Document-instantie vast over verzoeken heen. De documentservice is niet-gedeeld, juist om dit te voorkomen.

Oplossen: roep PdfFactory::create() aan binnen de request-scoped methode. Sla het teruggegeven document nooit op in een gedeelde service.

Referentie voor diagnostische commando’s

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Conformiteit

Elke rij is een normatieve bewering die op deze pagina wordt gedaan en is gekoppeld aan een volledige 64-hex reference_id uit het afgeschermde corpus van de standards development organization (SDO). De herkomst, waaronder het corpusmanifest en het ophaaltransport, staat in _sidecars/rag-citations.yaml.

Specificatie	Clausule	reference_id	Bewering
PSR-11	psr_11_container#1.1.2.p4		Identifier-contract voor has()/get() van de container

Zie ook

• /integrations/symfony/install/ — installatie en registratie.
• /integrations/symfony/configuration/ — volledig schema en beperkingen.
• /integrations/symfony/boot-and-discovery/ — detectie en opstartvolgorde.
• /integrations/symfony/security-and-operations/ — beveiligingsheaders en padvalidatie.