Riferimento API per Symfony

In sintesi

Il pacchetto Symfony espone la registrazione del bundle, un albero di configurazione, una factory iniettabile per creare nuovi documenti, helper per le risposte HTTP e tipi Messenger per la generazione asincrona. Nel codice applicativo, in genere, servono soltanto due simboli: il servizio PdfFactory, da iniettare per costruire un Document, e l’helper PdfResponse, che trasforma quel documento in una risposta HTTP sicura. Gli altri simboli (bundle, estensione, compiler pass, albero di configurazione, DTO di Messenger e handler) costituiscono il cablaggio da configurare una sola volta o gestito automaticamente dal framework.

Per iniziare: per un primo utilizzo, iniettare NextPDF\Symfony\Service\PdfFactory, chiamare create() per ottenere un Document nuovo e restituirlo con NextPDF\Symfony\Http\PdfResponse::download(). Il primo esempio qui sotto fa esattamente questo.

Attività comuni

Tre snippet eseguibili coprono le operazioni più frequenti. Ciascuno usa solo i simboli verificati documentati nelle tabelle successive.

Per restituire un PDF come download da un controller, iniettare la factory, costruire un documento e passarlo all’helper di risposta:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Cosa fa: PdfFactory::create() restituisce un Document nuovo e preconfigurato. PdfResponse::download() lo invia con Content-Type: application/pdf, una disposizione di tipo allegato e gli header di sicurezza fissi del bundle.

Per trasmettere in streaming un PDF di grandi dimensioni e mantenere basso il picco di memoria, usare l’helper di streaming e restituire una StreamedResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Cosa fa: PdfResponse::streamDownload() emette il PDF materializzato in blocchi e omette Content-Length; usare streamInline() per l’equivalente inline.

Per richiedere la generazione asincrona di un PDF, inviare un GeneratePdfMessage a un transport di Messenger in modo che il rendering venga eseguito su un worker:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Cosa fa: il DTO trasporta una class-string del builder e un percorso di output convalidato. L’handler risolve il builder, costruisce il documento e lo salva sul worker. La classe del builder implementa PdfBuilderInterface ed è registrata in un service locator (vedere la guida rapida Symfony per il cablaggio del locator e del worker).

Factory

Consultare questa tabella quando occorrono il costruttore esatto e il contratto create() del servizio iniettabile che produce nuovi documenti.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: factory di base; defaults: creator, autore, lingua, margini; pdfa: profilo PDF/A facoltativo; artisanConfig: configurazione facoltativa del renderer Chrome.	I valori predefiniti vengono applicati solo se configurati.	PdfFactory	Errori di cablaggio del container.	Il servizio può essere singleton perché create() restituisce un documento nuovo.
PdfFactory::create()	nessuno.	Applica creator e lingua; applica l’autore solo quando non è vuoto; applica PDF/A e la configurazione Artisan solo quando disponibili.	NextPDF\Core\Document	Errori di configurazione di base.	Chiamare una volta per richiesta, comando o messaggio.
PdfFactory::setArtisanAvailable(bool $available)	available: flag di disponibilità in fase di compilazione.	Disabilitato finché il compiler pass non lo abilita.	void	nessuno previsto.	Hook interno chiamato dal compiler pass dell’estensione facoltativa.
PdfFactory::setProAvailable(bool $available)	available: flag di disponibilità in fase di compilazione.	Disabilitato finché il compiler pass non lo abilita.	void	nessuno previsto.	Hook interno per la disponibilità di Premium.

Bundle, estensione e configurazione

Questa tabella copre il livello di cablaggio: consultarla quando si registra il bundle, si risolve l’albero di configurazione nextpdf o si traccia il rilevamento delle estensioni facoltative. La seconda tabella elenca le chiavi di configurazione vere e proprie.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
NextPdfBundle::build(ContainerBuilder $container)	Container builder di Symfony.	Chiama il metodo build della classe padre e registra OptionalExtensionPass.	void	Errori di registrazione del compiler pass.	Abilita il rilevamento delle funzionalità facoltative Artisan e Premium.
NextPdfBundle::getPath()	nessuno.	Restituisce il percorso radice del pacchetto.	string	nessuno previsto.	Utilizzato dal rilevamento dei bundle di Symfony e dal caricamento delle risorse.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Array di configurazione utente e container builder.	Elabora la configurazione nextpdf, memorizza i parametri risolti, carica le definizioni dei servizi e quindi verifica le estensioni richieste.	void	Errori di convalida della configurazione, di caricamento dei servizi o di estensione mancante.	Le estensioni richieste sono mbstring e zlib.
NextPdfExtension::getAlias()	nessuno.	Usa nextpdf come chiave di configurazione radice.	string	nessuno previsto.	Configurare il bundle sotto nextpdf:.
Configuration::getConfigTreeBuilder()	nessuno.	Definisce l’albero di configurazione nextpdf convalidato.	TreeBuilder	Errori di definizione della configurazione di Symfony.	Ricalca la forma della configurazione di Laravel dove possibile.
OptionalExtensionPass::process(ContainerBuilder $container)	Container builder di Symfony.	Rileva i servizi facoltativi Artisan e Premium e imposta i flag di disponibilità della factory.	void	Errori di cablaggio del compiler pass.	Viene eseguito durante la compilazione del container.

Chiave di configurazione	Tipo	Comportamento predefinito	Note
page_format	enum	A4; i valori consentiti includono A3, A5, Letter, Legal e Tabloid.	Si applica alla creazione predefinita dei documenti.
orientation	enum	P; i valori consentiti sono P e L.	Usare chiamate esplicite sul documento quando una pagina necessita di un orientamento diverso.
unit	enum	mm; i valori consentiti sono pt, mm, cm e in.	Mantiene i valori predefiniti del framework allineati alle unità di base.
pdfa	`string	null`	null; i valori consentiti sono 4, 4e e 4f.
fonts_path / cache_path	string	Percorso dei font del progetto e percorso della cache del kernel.	Mantenere entrambi i percorsi leggibili o scrivibili in base al ruolo di runtime.
signature.*	array	Disabilitato per impostazione predefinita con livello di firma B-B.	Fornisce certificato, chiave, password, certificati aggiuntivi e livello.
tsa.*	array	Disabilitato quando l’URL è null; il timeout predefinito è di 30 secondi.	Supporta credenziali, file mTLS, pin di chiave pubblica e criteri HTTP.
ocsp_cache.*	array	Abilitato con un TTL di 86400 secondi.	Utilizzato nei flussi di convalida e di firma a lungo termine quando disponibile.
messenger.*	array	Transport async, timeout 120, tentativi 3.	Utilizzato nei flussi di generazione asincrona.
artisan.*	array	Renderer Chrome disabilitato a meno che non sia configurato e installato.	Esegue il mapping su ChromeRendererConfig quando il renderer facoltativo è disponibile.
defaults.*	array	Creator NextPDF, autore vuoto, lingua en, margini e font predefiniti.	Applicato da PdfFactory::create().

Risposte HTTP

Usare questa tabella per scegliere l’helper di risposta corretto (visualizzazione inline o download, risposta bufferizzata o streaming) e per vedere il comportamento di ciascuno rispetto a nome file e header.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: documento costruito; filename: nome file della risposta.	Aggiunge .pdf quando manca.	Symfony\Component\HttpFoundation\Response	Errori di serializzazione di base.	Imposta il content type PDF e gli header difensivi.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Come inline; la disposizione è allegato.	Risposta per il download nel browser.	Response	Come inline.	Usare per download espliciti.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Come inline.	Emette i byte del PDF materializzato a blocchi.	StreamedResponse	Come inline.	Non evita la materializzazione del documento.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Come streamInline; la disposizione è allegato.	Risposta di download in streaming.	StreamedResponse	Come streamInline.	Applicare il criterio relativo alla dimensione dell’output prima del rendering.

Messenger

Consultare questa tabella quando si costruisce il flusso asincrono: il DTO del messaggio da inviare, l’interfaccia del builder da implementare e l’handler eseguito sul worker.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string che implementa PdfBuilderInterface; outputPath: destinazione .pdf; builderContext: dati serializzabili.	Array di contesto vuoto.	DTO del messaggio.	InvalidArgumentException per FQCN non valido, stream wrapper, byte null, traversal, percorso vuoto o destinazione non .pdf.	I transport di Messenger trasportano dati, non closure.
PdfBuilderInterface::build(Document $document, array $context): Document	document: documento configurato nuovo; context: dati serializzabili del messaggio.	Nessun contesto predefinito oltre a quello del messaggio.	Document configurato.	Eccezioni specifiche del builder.	Mantenere i builder deterministici e idempotenti.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	Factory PDF e service locator dei builder con tag.	Durante la costruzione non viene creato alcun documento.	GeneratePdfHandler	Errori di cablaggio del container.	Il locator deve esporre solo implementazioni di PdfBuilderInterface.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: DTO del messaggio convalidato.	Risolve il builder dal container, costruisce il documento e lo salva.	void	Servizio del builder mancante, risultato del builder non valido, errori di scrittura di base.	Preferire i builder come servizi rispetto alle callback statiche.

Note di sviluppo

• Non memorizzare un Document come servizio. Memorizzare PdfFactory e chiamare create() per ogni unità di lavoro.
• Accodare solo contesto serializzabile. Non inserire stream aperti, closure o oggetti request in builderContext.
• Mantenere il criterio relativo al percorso di output più restrittivo del DTO quando il deployment ha radici di archiviazione specifiche per tenant.