Configurazione del pacchetto Laravel NextPDF

In breve

config/nextpdf.php viene pubblicato con php artisan vendor:publish --tag=nextpdf-config. Ogni chiave prevede un fallback tramite variabile d’ambiente e un valore predefinito codificato direttamente. Questa pagina documenta ogni chiave esattamente come appare nel file config/nextpdf.php del pacchetto.

Installazione

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

Il provider unisce inoltre i valori predefiniti del pacchetto sotto la chiave di configurazione nextpdf durante register(). Le chiavi non impostate ricadono quindi sui valori riportati di seguito anche prima della pubblicazione.

Panoramica concettuale

La maggior parte delle variabili d’ambiente accetta un nome NEXTPDF_* oppure uno legacy TCPDF_*. Il prefisso legacy è supportato durante il periodo di transizione documentato in UPGRADE.md; le nuove installazioni devono usare la forma NEXTPDF_*. Il file di configurazione risolve i valori secondo questo ordine: variabile d’ambiente → valore del file pubblicato → valore predefinito del pacchetto.

Superficie API — chiavi di configurazione

Layout del documento

Chiave	Env (primaria)	Predefinito	Effetto
page_format	NEXTPDF_PAGE_FORMAT	A4	Formato di pagina predefinito (A4, A3, A5, Letter, Legal, Tabloid)
orientation	NEXTPDF_ORIENTATION	P	Verticale (P) o orizzontale (L)
unit	NEXTPDF_UNIT	mm	Unità di misura (pt, mm, cm, in)
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadati del creatore del documento; applicati al binding PdfDocumentInterface del documento
defaults.author	NEXTPDF_AUTHOR	(vuoto)	Metadati dell’autore; applicati solo se non vuoti
defaults.language	NEXTPDF_LANG	en	Lingua del documento; applicata al binding del documento
defaults.margin_top / _right / _bottom / _left	—	10	Margini predefiniti
defaults.font_family	—	dejavusans	Famiglia di font predefinita
defaults.font_size	—	12	Dimensione del font predefinita
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] in punti, oppure null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] in punti, oppure null

Il provider applica defaults.creator, defaults.language e (quando impostato) defaults.author a ogni documento appena risolto. Il ramo relativo a defaults.author viene saltato quando il valore è vuoto.

Archiviazione e colore

Chiave	Env (primaria)	Predefinito	Effetto
pdfa	NEXTPDF_PDFA	null	Livello di archiviazione PDF/A (null, 4, 4e, 4f). Un valore diverso da null abilita PDF/A sul binding del documento e richiede nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Directory per font TrueType aggiuntivi; controlla il percorso di ricerca del registro dei font
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Directory per la cache dei font analizzati e dei file temporanei
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Percorso del profilo ICC RGB; obbligatorio per PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Profilo ICC CMYK opzionale per i flussi di lavoro di stampa
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Usare flock sulla cache dei font per prevenire la corruzione quando worker di coda concorrenti vi scrivono

Impostare pdfa su un valore diverso da null richiede il livello Premium. Senza nextpdf/premium, la risoluzione del binding del documento con pdfa impostato solleva un errore di classe non trovata per il tipo di versione PDF/A. Questa pagina non descrive il comportamento di archiviazione Premium; consultare la documentazione Premium.

Memoria dei worker (runtime di lunga durata)

Chiave	Env (primaria)	Predefinito	Effetto
preload_fonts	—	[]	Elenco dei percorsi assoluti dei file di font analizzati all’avvio del worker. Il registro dei font viene bloccato dopo il warmup
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Budget della cache LRU delle immagini in MB. 0 disabilita la cache. Il provider non impone alcun limite superiore

Il provider non impone alcun limite superiore al budget della cache immagini. Applicare un limite di memoria del container o php.inimemory_limit per contenerlo. Il file di configurazione consiglia un massimo pratico di 256 MB.

Firma digitale (Premium)

Chiave	Env (primaria)	Predefinito	Effetto
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Quando vale false (o il certificato è vuoto), SignerInterface si risolve in null
signature.certificate	NEXTPDF_SIGN_CERT	null	Percorso del certificato di firma
signature.private_key	NEXTPDF_SIGN_KEY	null	Percorso della chiave privata
signature.password	NEXTPDF_SIGN_PASSWORD	(vuoto)	Passphrase della chiave
signature.extra_certs	—	[]	Percorsi dei certificati delle CA intermedie
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Livello baseline PAdES passato al signer

Il pacchetto Core documentato qui non include un signer concreto; il binding SignerInterface si risolve in null finché nextpdf/premium non fornisce un signer. Con Premium, level: B-B produce una firma baseline PAdES B-B. I livelli baseline PAdES superiori dipendono da un’autorità di marca temporale configurata e dalla funzionalità Premium; questa pagina non documenta tali livelli.

Autorità di marca temporale

Chiave	Env (primaria)	Predefinito	Effetto
tsa.url	NEXTPDF_TSA_URL	null	Endpoint TSA. Se è vuoto, TsaClient si risolve in null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(vuoto)	Credenziali HTTP per la TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Certificato / chiave client per mTLS verso la TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Timeout HTTP in secondi per il client PSR-18
tsa.pinned_public_keys	—	[]	Pin SPKI SHA-256 in Base64 (RFC 7469). Un valore vuoto disabilita il pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Emette un avviso quando la TSA presenta uno SPKI non incluso nei pin
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Consente HTTP in chiaro verso la TSA. Mantenere false in produzione

Cache delle risposte OCSP

Chiave	Env (primaria)	Predefinito	Effetto
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Memorizza in cache le risposte OCSP durante la convalida
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL della cache in secondi
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Directory della cache; null mantiene la cache solo in memoria

Coda

Chiave	Env (primaria)	Predefinito	Effetto
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Connessione della coda; null usa la connessione predefinita
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Nome della coda a cui viene inviato GeneratePdfJob
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Timeout del job in secondi

Renderer CDP Chrome (estensione Artisan)

Chiave	Env (primaria)	Predefinito	Effetto
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	valore env o non impostato	Percorso del binario Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Timeout di rendering in secondi
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(vuoto)	CSS predefinito iniettato nell’HTML renderizzato
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Disabilita la sandbox di Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Dimensione massima dell’input HTML in byte

La sezione artisan viene applicata al binding del documento solo se è presente una classe browser-factory di Chrome (l’estensione nextpdf/artisan). Se è assente, la sezione viene ignorata.

Esempio di codice — Produzione

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Casi limite e insidie

• signature.enabled = true con signature.certificate vuoto porta comunque alla risoluzione di SignerInterface in null; entrambi devono essere impostati.
• tsa.url = null forza TsaClient a null, anche se altre chiavi tsa.* sono popolate.
• signature.level = null fa fallback a PAdES B-B sul signer.
• image_cache_mb impostato su null (non 0) ricade sul valore predefinito di 50 MB; 0 disabilita esplicitamente la cache.
• Le variabili d’ambiente legacy TCPDF_* rimangono leggibili ma sono deprecate; eseguire la migrazione a NEXTPDF_*.

Prestazioni

La lettura della configurazione è un accesso O(1) a un array. preload_fonts scambia un’analisi una tantum O(f) all’avvio del worker con una latenza più bassa alla prima richiesta. Un valore più grande di image_cache_mb riduce la decodifica ripetuta delle immagini al costo di una maggiore memoria residente nel processo.

Note sulla sicurezza

tsa.allow_insecure_http indebolisce l’attendibilità della marca temporale e deve rimanere false in produzione. Gli URL TSA devono provenire esclusivamente da configurazioni attendibili; se sono esposti tramite un’interfaccia di amministrazione, applicare un firewall in uscita o un criterio DNS per mitigare la falsificazione delle richieste. Vedere /integrations/laravel/security-and-operations/.

Conformità

Nessuno standard normativo disciplina la struttura del file di configurazione; tutte le chiavi sono verificate rispetto al file config/nextpdf.php del pacchetto nella revisione documentata. La semantica dei livelli di firma è regolata da Premium ed esula dall’ambito di questa pagina Core.

Contesto commerciale

Le sezioni signature e tsa controllano la firma Premium quando è installato nextpdf/premium. 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/install/ — pubblicazione del file di configurazione
• /integrations/laravel/production-usage/ — configurazione applicata in un controller reale
• /integrations/laravel/security-and-operations/ — messa in sicurezza delle impostazioni della TSA e della coda
• /integrations/laravel/boot-and-discovery/ — quale binding è controllato da ciascuna chiave