Integrare NextPDF con Laravel

In breve

Questa guida pratica mostra come integrare NextPDF in un’applicazione Laravel 12. Il percorso si articola in sei fasi: installare il pacchetto, lasciare che Laravel lo rilevi automaticamente, pubblicare la configurazione, risolvere i binding del container, restituire una risposta HTTP ed eseguire un job in coda. Per ogni fase è indicata la documentazione di riferimento approfondita dell’area corrispondente.

Installazione

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

Boot e auto-discovery

Laravel rileva automaticamente il service provider e l’alias della facade dal blocco composer.jsonextra.laravel del pacchetto. Non è necessario modificare config/app.php. La mappa di autoload contiene una sola voce PSR-4. Il prefisso NextPDF\Laravel\ viene risolto in src/Laravel/, secondo la regola PSR-4 di corrispondenza tra prefisso e directory di base (PSR-4 §3). Il provider è di tipo deferred ed esegue il boot quando una delle voci del suo provides() viene risolta per la prima volta. I dettagli interni completi del processo di discovery sono descritti in /integrations/laravel/boot-and-discovery/.

Binding del container

Risolvere il contratto del documento tramite il container. Un identificatore associato viene risolto nella voce registrata corrispondente (PSR-11 §1.1.2). Il binding del documento è una factory, quindi ogni risoluzione restituisce un nuovo documento. I registri dei font e delle immagini sono singleton, quindi ogni risoluzione restituisce la stessa istanza condivisa. La tabella completa dei lifetime dei binding è disponibile in /integrations/laravel/overview/ e /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

Pubblicare la configurazione

php artisan vendor:publish --tag=nextpdf-config

Questo comando scrive config/nextpdf.php. Ogni chiave, con la relativa variabile d’ambiente e il relativo valore predefinito, è documentata in /integrations/laravel/configuration/.

Smoke test del service provider/bundle

Il pacchetto include una suite di test basata su Testbench che verifica il provider dall’inizio alla fine. Ecco uno smoke test minimo da aggiungere a un’applicazione che usa il pacchetto:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Queste due asserzioni riprendono i controlli di conformità use-once presenti in EInvoiceServiceProviderIntegrationTest nel pacchetto. Confermano che il documento è associato come factory e che il registro dei font è un singleton bloccato.

Punti di accesso dell’API pubblica

Punto di accesso	Scopo	Riferimento
`NextPDF\Laravel\Facades\Pdf`	Proxy statico verso un nuovo documento	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Documento risolto dal container	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Risposte HTTP inline / di download / in streaming	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Generazione in coda	/integrations/laravel/production-usage/

Esempio di codice — Produzione

Il controller, integrato tramite dependency injection e con gestione degli errori, è documentato per intero in /integrations/laravel/production-usage/. Nella stessa pagina è documentato anche il job in coda, con le relative callback di successo e di errore.

Casi limite e insidie

Risolvere PdfDocumentInterface, non il Document concreto. In questo modo il binding resta testabile e sostituibile.
SignerInterface e TsaClient vengono risolti in null finché non vengono configurati. Verificare sempre il valore null.
I contratti e-invoice richiedono nextpdf/premium. Sono comunque associati, ma generano un errore alla prima risoluzione in sua assenza.

Prestazioni

L’integrazione end-to-end non aggiunge alcun costo di boot, perché il provider è di tipo deferred. I costi di istanziazione alla prima risoluzione e i costi di warmup dei font sono descritti in /integrations/laravel/boot-and-discovery/.

Note sulla sicurezza

PdfResponse applica un set fisso di header OWASP. GeneratePdfJob convalida il proprio percorso di output nel worker. Il modello delle minacce è descritto in /integrations/laravel/security-and-operations/.

Conformità

Asserzione	Fonte	Clausola	reference_id
L’identificatore associato viene risolto nella voce registrata corrispondente	PSR-11 Container	§1.1.2
Il prefisso PSR-4 corrisponde alla directory di base	PSR-4 Autoloader	§3

Contesto commerciale

I contratti di firma, PDF/A ed e-invoice si integrano attraverso lo stesso provider quando nextpdf/premium è installato. Si tratta di una funzionalità Enterprise opzionale. Il pacchetto Core documentato qui non richiede alcuna modifica al codice per adottarla. Vedere https://nextpdf.dev/get-license/?intent=laravel-signing.

Vedere anche

/integrations/laravel/overview/ — architettura e tabella dei binding
/integrations/laravel/install/ — installazione ed estensioni opzionali
/integrations/laravel/quickstart/ — primo esempio eseguibile
/integrations/laravel/production-usage/ — DI, gestione degli errori, coda
/integrations/laravel/boot-and-discovery/ — discovery e lifetime