Panoramica dell'integrazione Symfony di NextPDF

In breve

nextpdf/symfony è il bundle ufficiale per Symfony 7 del motore NextPDF. Collega il motore al container di Symfony e fornisce una factory di documenti iniettabile nei servizi dell’applicazione. Include inoltre helper per le risposte HTTP e un percorso per generare PDF in modo asincrono, così l’elaborazione può essere eseguita in background.

Cosa fornisce il bundle

NextPDF Symfony integra il motore nextpdf/core in un’applicazione Symfony come bundle standard. Aggiunge i componenti seguenti, ciascuno verificato rispetto al codice sorgente del bundle in src/Symfony/:

• Un punto di ingresso del bundle — NextPDF\Symfony\NextPdfBundle estende la classe base Bundle di Symfony e registra un compiler pass.
• Un’estensione di dependency injection — NextPDF\Symfony\DependencyInjection\NextPdfExtension carica le definizioni dei servizi, converte l’albero di configurazione in parametri del container ed espone l’alias di configurazione nextpdf.
• Un albero di configurazione tipizzato — NextPDF\Symfony\DependencyInjection\Configuration definisce lo schema di configurazione nextpdf. Lo schema convalida i valori enum, imposta i valori predefiniti e usa i placeholder di parametro %kernel.*%.
• Una factory di documenti iniettabile — NextPDF\Symfony\Service\PdfFactory produce nuove istanze preconfigurate di NextPDF\Core\Document. È l’equivalente Symfony di una facade statica.
• Helper per le risposte HTTP — NextPDF\Symfony\Http\PdfResponse costruisce risposte inline, di download e in streaming con un insieme fisso di header di sicurezza allineati a OWASP.
• Un percorso di generazione asincrona — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler e NextPDF\Symfony\Message\PdfBuilderInterface si integrano con Symfony Messenger, così il rendering dei PDF può essere eseguito su un worker.
• Un rilevatore di estensioni in fase di compilazione — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass individua le estensioni NextPDF opzionali e registra i relativi servizi solo quando tali estensioni sono presenti.

Contratto del container

Il bundle registra nel container un insieme ridotto e stabile di servizi pubblici. Il servizio di documento nextpdf.document (con alias NextPDF\Contracts\PdfDocumentInterface e NextPDF\Core\Document) non è condiviso: a ogni risoluzione restituisce un documento distinto, destinato a un singolo uso. Questo è conforme al contratto del container PSR-11, secondo cui due chiamate successive a get() con lo stesso identificatore possono restituire valori diversi a seconda della configurazione del container — vedere PSR-11 §1.1.2. Il binding non condiviso è intenzionale: un documento accumula stato a ogni rendering, quindi creare una nuova istanza per ogni richiesta impedisce allo stato di propagarsi tra le richieste nei worker a lunga esecuzione.

Il registro dei font (NextPDF\Contracts\FontRegistryInterface) funziona in modo opposto: è un singleton condiviso. Il registro delle immagini è contrassegnato con il tag kernel.reset, quindi la sua cache limitata viene svuotata tra una richiesta e l’altra con i worker FrankenPHP e Messenger. La pagina di configurazione riporta la tabella completa dei servizi e degli alias.

Logging opzionale

I registri dei font e delle immagini accettano un logger PSR-3 opzionale. Il bundle associa Psr\Log\LoggerInterface solo quando l’applicazione ne fornisce uno (nullOnInvalid()). Il logging resta quindi un collaboratore opzionale, non una dipendenza obbligatoria. Questo è coerente con il contratto del logger PSR-3, secondo cui un logger è un collaboratore iniettato e sostituibile (PSR-3).

Funzionalità core rispetto a quelle opzionali

Il bundle è di per sé software core Apache-2.0. Alcune funzionalità sono disponibili solo installando anche un pacchetto opzionale:

Funzionalità	Richiede	Rilevamento
Generazione di PDF, PdfFactory, PdfResponse	solo core	sempre disponibile
Generazione asincrona	symfony/messenger	l’handler si attiva quando Messenger è installato
Rendering HTML tramite Chrome CDP	nextpdf/artisan	controllo class_exists in fase di compilazione
Archiviazione PDF/A, firme digitali	nextpdf/premium (installa Pro)	controllo class_exists in fase di compilazione

Quando nextpdf/premium è installato, il bundle può applicare una configurazione di base per firme PAdES B-B. I profili di firma di livello superiore non rientrano nell’ambito della documentazione di questo bundle. Per la matrice delle edizioni, consultare la documentazione di NextPDF Premium.

Quando utilizzare questo bundle

Utilizzare nextpdf/symfony quando si generano PDF all’interno di un’applicazione HTTP o di un worker Symfony 7. Il bundle fornisce servizi gestiti dal container, registri sicuri per i worker e risposte di download sicure, quindi non è necessario collegare manualmente il motore. Se serve generare PDF solo occasionalmente in uno script, è sufficiente il solo pacchetto core nextpdf/core.

Conformità

Ogni riga rappresenta un’asserzione normativa formulata in questa pagina, ancorata a un reference_id completo di 64 caratteri esadecimali tratto dal corpus SDO ad accesso riservato. La provenienza (manifest del corpus, trasporto di recupero) è indicata in _sidecars/rag-citations.yaml.

Specifica	Clausola	reference_id	Asserzione
PSR-11	psr_11_container#1.1.2.p3.b		Contratto del valore restituito da get() del container
PSR-3	psr_3_logger#x3.p17		Dipendenza opzionale LoggerInterface

Contesto commerciale

Le firme digitali e l’archiviazione PDF/A diventano disponibili quando nextpdf/premium (Pro) è installato insieme al bundle. Si tratta di funzionalità Pro opzionali. Il bundle Core qui documentato non richiede alcuna modifica al codice per adottarle. Vedere </get-license/?intent=symfony-pro>.

Vedere anche

• /integrations/symfony/install/ — installare e registrare il bundle.
• /integrations/symfony/configuration/ — l’albero di configurazione nextpdf completo e la tabella dei servizi.
• /integrations/symfony/quickstart/ — un controller eseguibile e un esempio asincrono.
• /integrations/symfony/boot-and-discovery/ — come Symfony rileva e avvia il bundle.
• /integrations/symfony/production-usage/ — sicurezza dei worker, streaming e pattern asincroni.