Guida rapida di NextPDF Laravel

In breve

In questo tutorial si genera un PDF scaricabile da un controller. Successivamente, lo stesso lavoro viene spostato in un job in coda. Ogni snippet corrisponde a un comportamento verificato dalla suite di test del pacchetto.

Installazione

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Panoramica concettuale

Tre punti di ingresso coprono la maggior parte dei casi d’uso di Laravel. La facade offre il punto di partenza più rapido. PdfResponse trasforma un documento in una risposta HTTP. Un job in coda sposta la generazione più pesante fuori dal thread della richiesta, in modo che l’utente non debba attenderla. Questo tutorial li illustra in sequenza. Le versioni per la produzione, che aggiungono la gestione degli errori, sono disponibili in /integrations/laravel/production-usage/.

Esempio di codice — Avvio rapido

1. Facade

A ogni chiamata, la facade risolve un nuovo documento dal container. Il container è il registro dei servizi di Laravel. Questo snippet corrisponde al comportamento verificato da tests/Unit/Laravel/Facades/PdfTest.php.

<?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'));

2. Risposta di download da un controller

PdfResponse::download() restituisce una Illuminate\Http\Response con Content-Type: application/pdf, disposition attachment e intestazioni di sicurezza OWASP. tests/Unit/Laravel/Http/PdfResponseTest.php verifica il codice di stato, il content type, il prefisso della disposition e le intestazioni.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Per un’anteprima inline nel browser, sostituire download() con inline(). Per documenti di grandi dimensioni, usare streamInline() o streamDownload(). Questi inviano il PDF in blocchi deterministici da 64 KB.

3. Generazione in coda

GeneratePdfJob genera e salva un PDF su un worker della coda. La closure del builder riceve il documento risolto dal container e restituisce il documento configurato. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php conferma che il job crea il file nel percorso di output esatto.

<?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),
);

Il percorso di output deve terminare con .pdf. Il job convalida il percorso sul worker prima della scrittura.

Esempio di codice — Produzione

Le versioni per la produzione aggiungono gestione esplicita degli errori, callback di successo e di errore sul job e una strategia tipizzata per le eccezioni. Sono documentate in dettaglio in /integrations/laravel/production-usage/.

Casi limite e insidie

La facade restituisce un’istanza di documento diversa a ogni risoluzione. Non memorizzare nella cache Pdf::getFacadeRoot() tra documenti logici distinti.
Un nome di file vuoto passato a una qualsiasi factory PdfResponse usa per impostazione predefinita document.pdf. La suite di test della risposta verifica questo valore predefinito.
I nomi di file non ASCII ricevono automaticamente un parametro RFC 5987 filename*=. I nomi ASCII non lo ricevono.
GeneratePdfJob rifiuta path traversal, stream wrapper, byte null e qualsiasi estensione diversa da .pdf. Genera InvalidArgumentException sul worker.

Prestazioni

Un documento di una sola pagina rientra ampiamente nel budget di tempo per pagina indicato nel front matter. Spostando la generazione su GeneratePdfJob si elimina completamente il tempo di creazione del PDF dalla richiesta HTTP. La richiesta termina non appena il job viene inviato.

Note sulla sicurezza

PdfResponse e le factory applicano un set fisso di intestazioni OWASP. Inoltre sanificano il nome del file di download. Il job in coda convalida il proprio percorso di output. La copertura dettagliata delle minacce è in /integrations/laravel/security-and-operations/.

Conformità

Questo tutorial non è regolato da alcuno standard normativo. Ogni snippet è verificato rispetto al codice sorgente del pacchetto. È inoltre verificato rispetto al test corrispondente in tests/.

Contesto commerciale

L’output firmato e PDF/A è disponibile con nextpdf/premium. Si tratta di una funzionalità Enterprise opzionale. Il pacchetto Core qui documentato non richiede alcuna modifica al codice per adottarla. Consultare https://nextpdf.dev/get-license/?intent=laravel-signing.

Vedere anche

/integrations/laravel/install/ — installazione e pubblicazione della config
/integrations/laravel/production-usage/ — controller e job con dependency injection e gestione degli errori
/integrations/laravel/configuration/ — chiavi di config utilizzate qui
/integrations/laravel/overview/ — architettura e cicli di vita dei binding