Riferimento API Laravel

In breve

Il pacchetto nextpdf/laravel integra il core NextPDF, indipendente dal framework, in un’applicazione Laravel. Espone quattro elementi utilizzabili direttamente: la facciata Pdf per la creazione rapida, il binding del container PdfDocumentInterface per creare documenti tramite injection, l’helper PdfResponse che trasforma un documento completato in una risposta HTTP e il job in coda GeneratePdfJob per la generazione al di fuori della richiesta. Il NextPdfServiceProvider registra ogni binding e viene rilevato automaticamente, quindi non serve alcuna configurazione manuale. La configurazione in config/nextpdf.php determina i valori predefiniti, i font, la gestione delle code e le funzionalità opzionali di firma e TSA.

Punto di partenza: per inviare un PDF direttamente da un controller, creare un documento e restituire PdfResponse::download($document, 'file.pdf') — vedere il primo esempio qui sotto.

Attività comuni

Gli snippet seguenti coprono i tre flussi iniziali più comuni. Ciascuno è verificato rispetto al codice sorgente del pacchetto; seguono le tabelle complete per ogni simbolo.

Restituire un PDF scaricabile da un controller — l’attività più comune:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Cosa fa: inietta un nuovo documento, scrive una riga e restituisce una risposta di tipo attachment con Content-Type: application/pdf e le intestazioni di sicurezza OWASP. Sostituire download() con inline() per visualizzare l’anteprima nel browser.

Creare e salvare con la facciata Pdf — il percorso più breve per script e flussi semplici:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

Cosa fa: la facciata risolve un nuovo documento dal container, scrive una cella e salva il PDF completato su disco.

Generare un PDF fuori dal thread della richiesta con GeneratePdfJob:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Cosa fa: accoda la generazione su un worker. La closure builder riceve un documento risolto dal container e lo restituisce. Il job convalida il percorso di output .pdf prima di salvarlo. Il nome della coda, il timeout e la connessione provengono da config('nextpdf.queue.*').

Facciata

La facciata Pdf agisce da proxy statico verso un nuovo Document del core; usarla in flussi di controller brevi, dove lo stile statico resta leggibile. Ogni riga corrisponde a un metodo del documento sottoposto a proxy.

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Genera o fallisce con	Note
NextPDF\Laravel\Facades\Pdf	nessuno; l’accessor statico della facciata risolve NextPDF\Contracts\PdfDocumentInterface	Laravel risolve il binding corrente del container per l’interfaccia del documento.	L’API fluida del documento core sottostante.	Errore di binding del container Laravel se il provider non è registrato.	Usare la facciata per flussi di controller brevi. Per servizi e job, preferire la constructor injection.
Pdf::setTitle(string $title)	title: titolo del documento.	Sostituisce qualsiasi titolo precedente.	static	Errori di convalida del core o errori in fase di scrittura.	Sottoposto a proxy verso il Document del core.
Pdf::setAuthor(string $author)	author: metadati dell’autore del documento.	Sostituisce qualsiasi autore precedente.	static	Errori di convalida dei metadati del core.	Per i metadati a livello di applicazione, preferire i valori predefiniti configurati.
Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)	size: dimensione di pagina facoltativa; orientation: Portrait per impostazione predefinita.	Usa la dimensione di pagina configurata/predefinita quando size viene omesso.	static	Errori di convalida della pagina del core.	Usare un PageSize esplicito quando la dimensione di output è rilevante.
Pdf::setFont(string $family, string $style = '', float $size = 12.0)	Famiglia di font, stile e dimensione in punti.	Stile vuoto e dimensione di 12 pt.	static	Errori del registro dei font o di codifica.	Precaricare i font di produzione tramite nextpdf.preload_fonts quando la latenza è importante.
Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)	Riquadro della cella, testo, flag del bordo, flag di interruzione di riga, allineamento.	Testo vuoto, nessun bordo, nessuna interruzione di riga, allineamento a sinistra.	static	Errori di impaginazione o di codifica del testo.	Usare per un output semplice a impaginazione fissa.
Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)	Larghezza della cella, altezza di riga, testo, flag del bordo, allineamento.	Nessun bordo e allineamento a sinistra.	static	Errori di impaginazione o di codifica del testo.	Usare quando il testo deve andare a capo entro una larghezza fissa.
Pdf::writeHtml(string $html)	html: frammento HTML.	Esegue il rendering nella pagina corrente, creandone una quando necessario.	static	Errori di rendering HTML del core.	Applicare criteri su dimensioni dell’input e risorse prima di accettare HTML non attendibile.
Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)	Percorso del file e rettangolo di posizionamento facoltativo.	Consente al documento core di scegliere la posizione corrente e la dimensione intrinseca quando le coordinate vengono omesse.	static	Errori di decodifica dell’immagine, del percorso o di impaginazione.	Convalidare i criteri sull’origine delle immagini prima di accettare percorsi forniti dall’utente.
Pdf::output(?string $filename = null, OutputDestination $dest = Inline)	filename: nome facoltativo; dest: destinazione di output.	Output inline quando la destinazione viene omessa.	string	Errori di serializzazione del core.	Per le risposte HTTP di Laravel, preferire PdfResponse.
Pdf::save(string $path)	path: destinazione sul filesystem.	Scrive il PDF completato su disco.	void	Errori del filesystem o di scrittura del core.	Convalidare le directory di output nel codice dell’applicazione.
Pdf::getPdfData()	nessuno.	Materializza il PDF in memoria.	string	Errori di serializzazione del core.	Usare quando un altro oggetto del framework deve gestire il corpo della risposta.

Service provider e binding

Consultare questa tabella quando occorre risolvere o sovrascrivere direttamente una voce del container — per esempio per iniettare DocumentFactoryInterface in un servizio o per verificare che cosa espone provides().

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Genera o fallisce con	Note
NextPdfServiceProvider::register()	nessuno.	Esegue il merge di config/nextpdf.php, registra i registri, la document factory, il binding del documento, il client HTTP, il client TSA, il signer e i contratti opzionali per la fatturazione elettronica.	void	Errori di risoluzione del container o di classi opzionali quando si usa una funzionalità.	FontRegistryInterface e ImageRegistry sono condivisi; i documenti sono sempre nuovi.
NextPdfServiceProvider::boot()	nessuno.	Convalida le estensioni PHP richieste e pubblica nextpdf-config in modalità console.	void	RuntimeException se un’estensione richiesta non è disponibile.	Le estensioni richieste sono mbstring e zlib.
NextPdfServiceProvider::provides()	nessuno.	Segnala gli ID dei servizi differiti.	array<string>	nessuno previsto.	Include PdfDocumentInterface, DocumentFactoryInterface, FontRegistryInterface, SignerInterface, TsaClient, ClientInterface e nextpdf.
PdfDocumentInterface / nextpdf	risolto dal container Laravel.	Crea un Document monouso da DocumentFactoryInterface, quindi applica i valori predefiniti configurati e le impostazioni opzionali PDF/A o Artisan.	NextPDF\Core\Document	Errori delle estensioni opzionali quando sono configurate ma non disponibili.	Risolvere un nuovo documento per ogni richiesta o job.
DocumentFactoryInterface	risolto dal container Laravel.	Factory singleton che condivide i registri di font e immagini per la durata del processo.	DocumentFactoryInterface	Errori di configurazione del registro.	Usare questo per la dependency injection esplicita.
SignerInterface	risolto dal container Laravel.	Restituisce null a meno che nextpdf.signature.enabled e i percorsi dei certificati non siano configurati.	`SignerInterface	null`	Errori di caricamento del certificato o di convalida a livello di firma.

Configurazione

Usare questa tabella per consultare le chiavi nextpdf.* lette dai binding a runtime; il riferimento completo per ogni chiave, con variabili d’ambiente e valori predefiniti, è disponibile in /integrations/laravel/configuration/.

Chiave	Tipo	Comportamento predefinito	Note
nextpdf.fonts_path	string	Usa i font delle risorse di Laravel quando viene omesso.	Directory per i font personalizzati e il warmup.
nextpdf.cache_path	string	Percorso della cache dell’applicazione.	Mantenerlo scrivibile dal worker PHP.
nextpdf.preload_fonts	list<string>	Elenco vuoto.	Caricati durante la creazione del registro, che poi viene bloccato.
nextpdf.image_cache_mb	int	Dimensione massima della cache delle immagini.	Limita la memoria della cache delle immagini per la durata del processo.
nextpdf.defaults.*	array	Creatore NextPDF, lingua en, autore e valori predefiniti di impaginazione facoltativi.	Applicati a ogni documento nuovo.
nextpdf.artisan.*	array	Renderer Chrome disabilitato, salvo quando installato e configurato.	Mappa su ChromeRendererConfig::fromArray().
nextpdf.signature.*	array	Firma disabilitata per impostazione predefinita.	Certificato, chiave privata, password, certificati aggiuntivi e livello di firma.
nextpdf.tsa.*	array	TSA disabilitato quando l’URL è vuoto.	Supporta credenziali, file mTLS, timeout, pin di chiave pubblica e criteri HTTP.
nextpdf.ocsp_cache.*	array	Cache OCSP abilitata con il TTL configurato.	Utilizzata dai flussi di convalida della firma quando disponibile.

Risposte HTTP

Usare questa tabella quando si restituisce un documento completato via HTTP e occorre scegliere tra visualizzazione inline, download come allegato o output in streaming.

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Genera o fallisce con	Note
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: documento creato; filename: nome file della Content-Disposition.	I nomi file vuoti vengono normalizzati a document.pdf.	Illuminate\Http\Response	Errori di serializzazione del core o di costruzione della risposta.	Imposta il content type PDF e le intestazioni difensive.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Come inline; la disposition è attachment.	Risposta che avvia il download nel browser.	Illuminate\Http\Response	Come inline.	Usare per i download espliciti di file.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Come inline.	Materializza i byte del PDF, quindi emette blocchi da 64 KB.	Symfony\Component\HttpFoundation\StreamedResponse	Come inline.	Si tratta di output HTTP in streaming, non di rendering zero-copy.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Come streamInline; la disposition è attachment.	Risposta di download in streaming.	StreamedResponse	Come streamInline.	Applicare limiti di dimensione su input e output prima del rendering.

Job in coda

Usare questa tabella quando si sposta la generazione fuori dal thread della richiesta; copre la costruzione, il dispatch e l’aggiunta di callback di successo o di errore a GeneratePdfJob.

Simbolo	Parametri	Comportamento predefinito	Valori restituiti	Genera o fallisce con	Note
new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)	outputPath: percorso .pdf di destinazione; builder: riceve un PdfDocumentInterface; i callback sono facoltativi.	Il nome della coda, il timeout e la connessione vengono letti da config('nextpdf.queue.*').	Istanza del job.	Errori di serializzazione se il builder o i callback non possono essere serializzati.	Il builder deve restituire il documento configurato.
GeneratePdfJob::handle()	nessuno.	Risolve PdfDocumentInterface, applica il builder, convalida il percorso di output, quindi salva.	void	InvalidArgumentException per percorsi di output non sicuri; errori di scrittura del core.	Rifiuta gli stream wrapper, i byte null, i segmenti .. e i percorsi non .pdf.
GeneratePdfJob::failed(Throwable $exception)	exception: causa dell’errore.	Richiama il callback di errore configurato quando presente.	void	Errori dei callback.	Mantenere i callback idempotenti.
GeneratePdfJob::then(callable $callback)	callback: riceve il percorso di output.	Sostituisce il callback di successo.	self	Errori di serializzazione della closure.	Helper fluido per la configurazione del dispatch.
GeneratePdfJob::catch(callable $callback)	callback: riceve il Throwable sollevato.	Sostituisce il callback di errore.	self	Errori di serializzazione della closure.	Usare per avvisi o per la pulizia compensativa.

Note di sviluppo

• PdfResponse richiama sempre getPdfData() prima della costruzione della risposta. Non è un builder lazy per documenti.
• I payload delle code possono essere manomessi nei trasporti condivisi; mantenere i percorsi di output confinati in una directory di proprietà dell’applicazione.
• Usare un documento nuovo per ogni richiesta o job. Non riutilizzare un documento tra richieste diverse.