Risoluzione dei problemi del bundle Symfony di NextPDF

In breve

La maggior parte dei problemi rientra in quattro aree: individuazione, convalida della configurazione, collegamento nel container o routing di Messenger. Le sezioni seguenti associano ciascun sintomo al comportamento di verifica implementato nel codice sorgente del bundle e forniscono un comando della console per confermare la correzione.

Il bundle non è registrato

Sintomo: non è possibile collegare automaticamente PdfFactory oppure debug:container nextpdf non trova nulla.

Causa: il bundle non è stato aggiunto a config/bundles.php. Flex non è stato eseguito oppure l’applicazione non utilizza Flex.

Soluzione:

php bin/console debug:container nextpdf

Se l’output è vuoto, aggiungere il bundle manualmente:

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

La dichiarazione per la registrazione automatica si trova nel file composer.json del bundle, in extra.symfony.bundles. Si applica solo alle applicazioni con Flex abilitato.

L’avvio non riesce per un’estensione PHP mancante

Sintomo: il kernel genera una RuntimeException che menziona ext-mbstring o ext-zlib all’avvio.

Causa: è la protezione fail-fast intenzionale del bundle, NextPdfExtension::guardRequiredExtensions(). Non è un difetto.

Soluzione: abilitare l’estensione segnalata in php.ini e riavviare il runtime. Confermare con:

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

La configurazione viene rifiutata in fase di compilazione

Sintomo: si verifica una Symfony\Component\Config\Definition\Exception\InvalidConfigurationException durante cache:clear o cache:warmup.

Causa: un valore non rientra nello schema. Questi vincoli sono definiti in Configuration.php:

• page_format deve essere uno di A4, A3, A5, Letter, Legal, Tabloid.
• orientation deve essere P o L.
• unit deve essere uno di pt, mm, cm, in.
• pdfa deve essere null, 4, 4e o 4f.
• image_cache_mb deve essere >= 0.

Soluzione: visualizzare la configurazione risultante, quindi correggere la chiave problematica:

php bin/console debug:config nextpdf

PDF/A o la firma non producono effetto

Sintomo: pdfa o la sezione signature sono configurati, ma l’output resta un PDF ordinario.

Causa: queste funzionalità richiedono nextpdf/premium. PdfFactory applica PDF/A solo quando l’estensione Pro viene rilevata in fase di compilazione. Il compiler pass registra un firmatario solo quando signature.enabled è true e signature.certificate è impostato.

Soluzione: verificare che Premium sia installato e che il servizio del firmatario esista:

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

Se Premium è assente, il bundle memorizza la configurazione ma la lascia inerte per scelta progettuale. La funzionalità di firma documentata del bundle con Pro è il profilo di base B-B. La documentazione di NextPDF Premium descrive i profili oltre B-B.

Il rendering con Chrome non produce alcun effetto

Sintomo: la configurazione di artisan viene ignorata.

Causa: il rendering CDP di Chrome richiede nextpdf/artisan. Il compiler pass ne verifica la presenza con class_exists in fase di compilazione. Se l’estensione è assente, il renderer non viene mai collegato.

Soluzione:

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

La verifica viene eseguita durante la compilazione del container. Pertanto, dopo l’installazione dell’estensione, eseguire un nuovo cache:clear.

Il gestore di Messenger non viene mai chiamato

Sintomo: GeneratePdfMessage viene inviato ma non viene scritto alcun PDF.

Cause e soluzioni:

• Messaggio non instradato — aggiungere una voce di routing che mappi NextPDF\Symfony\Message\GeneratePdfMessage a un transport in config/packages/messenger.yaml, quindi avviare un worker (php bin/console messenger:consume <transport>).
• Builder assente nel locator — il gestore recupera il builder da un locator PSR-11 tramite il relativo id class-string. Un identificatore di container è una stringa che identifica univocamente una voce (PSR-11 §1.1.2). Se la classe del builder non è registrata nel locator, il gestore genera una RuntimeException che indica che il builder configurato deve implementare PdfBuilderInterface. Registrare il builder, quindi referenziarlo dal locator.

Esaminare il routing e il locator:

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

Messaggio rifiutato durante l’invio con InvalidArgumentException

Sintomo: la costruzione di GeneratePdfMessage genera una InvalidArgumentException.

Causa: il data transfer object (DTO) del messaggio convalida i propri input. Le regole di rifiuto applicate sono:

• percorso di output vuoto o contenente un byte null;
• uno schema di stream-wrapper (ad esempio php://...);
• un segmento di path-traversal .. (separatori POSIX o Windows);
• un percorso di output che non termina in .pdf (senza distinzione tra maiuscole e minuscole);
• una builderClass che non è un nome di classe sintatticamente valido.

Soluzione: passare un percorso assoluto del filesystem che termini in .pdf e un nome di classe del builder esistente e completo.

Un documento contiene dati obsoleti

Sintomo: un PDF generato include contenuti di una richiesta precedente.

Causa: un’istanza di Document è stata conservata tra più richieste in un worker a esecuzione prolungata. Il servizio del documento è dichiarato non condiviso proprio per evitare questo problema.

Soluzione: chiamare PdfFactory::create() all’interno del metodo con ambito di richiesta. Non memorizzare mai il documento restituito in un servizio condiviso.

Riferimento dei comandi di diagnostica

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

Conformità

Ogni riga è un’asserzione normativa formulata in questa pagina, ancorata a un reference_id completo di 64 cifre esadecimali proveniente dal corpus SDO con accesso controllato. La provenienza, relativa al manifest del corpus e al transport di recupero, si trova in _sidecars/rag-citations.yaml.

Specifica	Clausola	reference_id	Asserzione
PSR-11	psr_11_container#1.1.2.p4		Contratto dell’identificatore has()/get() del container

Vedere anche

• /integrations/symfony/install/ — installazione e registrazione.
• /integrations/symfony/configuration/ — schema completo e vincoli.
• /integrations/symfony/boot-and-discovery/ — individuazione e sequenza di avvio.
• /integrations/symfony/security-and-operations/ — intestazioni di sicurezza e convalida dei percorsi.