Installazione del pacchetto Laravel di NextPDF

In breve

Installare nextpdf/laravel tramite Composer. L’auto-discovery registra automaticamente il service provider. Pubblicare quindi il file di configurazione, così da poterlo modificare. Il pacchetto rileva in autonomia le eventuali estensioni facoltative di NextPDF.

Installazione

composer require nextpdf/laravel

Il pacchetto dichiara i seguenti vincoli nel proprio composer.json:

Requisito	Vincolo
PHP	`>=8.4 <9.0`
`laravel/framework`	`^12.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`psr/http-client`	`^1.0`

Il pacchetto utilizza l’autoload tramite un’unica mappa PSR-4. Il prefisso NextPDF\Laravel\ viene risolto in src/Laravel/. In questo modo viene rispettata la regola PSR-4 di corrispondenza tra prefisso e directory di base (PSR-4 §3).

Panoramica concettuale

Dopo aver eseguito composer require, l’auto-discovery dei pacchetti di Laravel legge il blocco extra.laravel nel composer.json di questo pacchetto. Registra quindi automaticamente il provider e l’alias della facade, quindi non è necessario modificare manualmente config/app.php. Il blocco è il seguente:

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

La documentazione dei pacchetti di Laravel descrive il funzionamento di questo meccanismo. L’array extra.laravel.providers registra automaticamente i service provider e l’array extra.laravel.aliases registra automaticamente gli alias delle facade (guida allo sviluppo di pacchetti per Laravel 12, https://laravel.com/docs/12.x/packages, consultata il 2026-05-18).

Esempio di codice — Avvio rapido

Pubblicare il file di configurazione con il tag nextpdf-config. Il nome del tag è definito in NextPdfServiceProvider::boot().

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

Il comando scrive config/nextpdf.php nell’applicazione. Il provider inoltre unisce la configurazione predefinita del pacchetto sotto la chiave nextpdf durante register(), quindi il pacchetto funziona anche prima della pubblicazione. La pubblicazione serve solo a rendere il file modificabile nell’applicazione.

Verificare che il provider venga rilevato:

php artisan package:discover --ansi

Esempio di codice — Produzione

Per distribuzioni riproducibili, bloccare il vincolo. Disabilitare esplicitamente il discovery solo quando il provider viene registrato manualmente:

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "nextpdf/laravel"
      ]
    }
  }
}

Quando il discovery è disabilitato, registrare manualmente il provider in bootstrap/providers.php:

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

Estensioni facoltative

Il pacchetto elenca i componenti aggiuntivi facoltativi nella sezione suggest del proprio composer.json. Il pacchetto li rileva in fase di esecuzione:

Pacchetto	Effetto dopo l’installazione	Punto di rilevamento
`nextpdf/artisan`	Quando è presente una classe factory di Chrome, la configurazione del renderer HTML Chrome CDP viene applicata al binding del documento	`NextPdfServiceProvider::register()` verifica la presenza della classe browser-factory di Chrome
`nextpdf/premium`	Le implementazioni concrete dei contratti per la firma (PAdES B-B), l’archiviazione PDF/A e la fatturazione elettronica vengono risolte tramite le chiavi del container esistenti	risolte in modo lazy alla prima risoluzione del container

Installare un’estensione allo stesso modo:

composer require nextpdf/artisan

Non è necessaria alcuna configurazione aggiuntiva. Il provider rileva l’estensione alla successiva registrazione.

Casi limite e insidie

La pubblicazione è idempotente. Non sovrascrive un config/nextpdf.php già esistente. Aggiungere --force quando si intende sovrascriverlo intenzionalmente.
Il provider è deferred, quindi è sufficiente eseguire php artisan package:discover per confermare il pacchetto. I binding non compaiono comunque fino alla prima risoluzione.
Il pacchetto supporta nextpdf/core su entrambe le linee major ^3.0 e ^5.2. Allineare il vincolo di core alla linea fissata dall’applicazione. La superficie dell’adapter Laravel è identica su entrambe.
Il badge del README e il composer.json concordano su Apache-2.0. Il pacchetto è stato rilicenziato a partire da LGPL-3.0-or-later. Le versioni con tag precedenti alla migrazione rimangono sotto la licenza precedente (vedere CHANGELOG.md).

Prestazioni

La risoluzione di nextpdf/core rappresenta la voce predominante nel costo di composer require. La registrazione del provider non aggiunge alcun costo di boot misurabile, poiché tutti i binding sono closure deferred. Il costo di costruzione alla prima risoluzione è documentato in /integrations/laravel/boot-and-discovery/.

Note sulla sicurezza

Installare dal pacchetto Packagist canonico nextpdf/laravel. Il pacchetto include intestazioni SPDX REUSE e un file NOTICE Apache-2.0. Bloccare il vincolo in composer.json ed eseguire il commit di composer.lock affinché i worker distribuiti risolvano l’albero delle dipendenze verificato.

Conformità

Dichiarazione	Fonte	Clausola	reference_id
Il prefisso PSR-4 corrisponde alla directory di base	PSR-4 Autoloader	§3

I nomi delle chiavi di auto-discovery di Laravel sono stati verificati rispetto alla documentazione ufficiale sullo sviluppo di pacchetti per Laravel 12 (https://laravel.com/docs/12.x/packages, consultata il 2026-05-18).

Contesto commerciale

nextpdf/premium aggiunge le implementazioni concrete per la firma, il PDF/A e la fatturazione elettronica. Si tratta di una funzionalità Enterprise facoltativa. 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 del pacchetto e tabella dei binding
/integrations/laravel/quickstart/ — primo controller eseguibile
/integrations/laravel/configuration/ — spiegazione di ogni chiave di configurazione
/integrations/laravel/boot-and-discovery/ — meccanismi interni del discovery e ciclo di vita dei binding