Configurare NextPDF per CodeIgniter 4

In sintesi

La configurazione risiede in NextPDF\CodeIgniter\Config\NextPdf, una sottoclasse di BaseConfig di CodeIgniter. Per sovrascrivere i valori, estendere la classe in app/Config/ oppure impostare chiavi .env con il prefisso nextpdf.. I valori predefiniti sono già utilizzabili senza configurazioni aggiuntive.

Panoramica concettuale

NextPdf è una BaseConfig tipizzata. Per scelta, non è final. Secondo la convenzione di CodeIgniter, la configurazione dell’applicazione estende la classe del pacchetto, così da poter sovrascrivere i valori predefiniti. Quando CodeIgniter costruisce la configurazione, BaseConfig risolve gli override d’ambiente per ogni proprietà pubblica. Questa risoluzione include anche le chiavi di array annidate.

I percorsi predefiniti dei font e della cache usano la costante WRITEPATH di CodeIgniter: WRITEPATH . 'fonts' e WRITEPATH . 'cache/nextpdf'.

Chiavi di configurazione

Ciascuna delle chiavi seguenti è una proprietà pubblica di NextPdf. I valori predefiniti sono quelli verificati nel codice sorgente del pacchetto.

Valori predefiniti di pagina e documento

Chiave	Tipo	Predefinito	Descrizione
`pageFormat`	`string`	`A4`	Formato di pagina.
`orientation`	`string`	`P`	`P` verticale o `L` orizzontale.
`unit`	`string`	`mm`	Unità di misura.
`defaults.creator`	`string`	`NextPDF`	Metadati del creatore del PDF.
`defaults.author`	`string`	`''`	Metadati dell’autore; omessi quando vuoti.
`defaults.language`	`string`	`en`	Tag della lingua del documento.
`defaults.margin_top`	`float`	`10.0`	Margine superiore.
`defaults.margin_right`	`float`	`10.0`	Margine destro.
`defaults.margin_bottom`	`float`	`10.0`	Margine inferiore.
`defaults.margin_left`	`float`	`10.0`	Margine sinistro.
`defaults.font_family`	`string`	`dejavusans`	Famiglia di font predefinita.
`defaults.font_size`	`float`	`12.0`	Dimensione predefinita del font.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim box, se impostato.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed box, se impostato.

Il pacchetto applica defaults.creator e defaults.language a ogni documento. Applica defaults.author solo quando tale valore è non vuoto.

Percorsi e cache

Chiave	Tipo	Predefinito	Descrizione
`fontsPath`	`string`	`WRITEPATH/fonts`	Directory dei file font.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Directory della cache.
`preloadFonts`	`list<string>`	`[]`	Percorsi assoluti dei font precaricati all’avvio.
`imageCacheMb`	`int`	`50`	Budget della cache LRU delle immagini in MB.
`fontCacheLocking`	`bool`	`true`	Blocca la cache dei font dopo il warm-up.

Il registro dei font rifiuta un fontsPath contenente uno stream wrapper (://) o un byte null. In tal caso viene generato un errore di runtime. Vedere /integrations/codeigniter/security-and-operations/.

Archiviazione e colore (NextPDF Pro)

Chiave	Tipo	Predefinito	Descrizione
`pdfa`	`string\|null`	`null`	Versione PDF/A: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Percorso del profilo ICC RGB.
`iccProfile.cmyk`	`string\|null`	`null`	Percorso del profilo ICC CMYK.

pdfa ha effetto solo quando NextPDF Pro è installato e la funzionalità di archiviazione è disponibile. Con il solo core, la chiave viene ignorata.

Firma digitale (NextPDF Pro / Enterprise)

Chiave	Tipo	Predefinito	Descrizione
`signature.enabled`	`bool`	`false`	Abilita il servizio di firma.
`signature.certificate`	`string\|null`	`null`	Percorso del file del certificato.
`signature.private_key`	`string\|null`	`null`	Percorso del file della chiave privata.
`signature.password`	`string`	`''`	Password della chiave privata.
`signature.extra_certs`	`list<string>`	`[]`	Percorsi dei certificati aggiuntivi della catena.
`signature.level`	`string`	`B-B`	Identificatore del livello di firma.

Services::pdfSigner() restituisce null se signature.enabled non è true oppure se signature.certificate è vuoto. Il livello predefinito è B-B. NextPDF Pro fornisce la firma baseline B-B. I livelli di validazione a lungo termine sono una funzionalità Enterprise distinta e sono documentati nel riferimento Premium, non qui.

PAdES B-T viene prodotto dal motore Core. L’integrazione CodeIgniter non aggiunge B-T di per sé e Pro fornisce solo la baseline B-B. Questa documentazione verrà aggiornata se e quando Pro B-T sarà disponibile.

Time Stamp Authority

Chiave	Tipo	Predefinito	Descrizione
`tsa.url`	`string\|null`	`null`	URL dell’endpoint TSA.
`tsa.username`	`string`	`''`	Nome utente per l’autenticazione di base TSA.
`tsa.password`	`string`	`''`	Password per l’autenticazione di base TSA.
`tsa.cert`	`string\|null`	`null`	Percorso del certificato client.
`tsa.key`	`string\|null`	`null`	Percorso della chiave client.
`tsa.timeout`	`int`	`30`	Timeout della richiesta in secondi.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Chiavi pubbliche TSA con pinning.
`tsa.warn_on_key_rotation`	`bool`	`true`	Avvisa in caso di rotazione della chiave TSA.
`tsa.allow_insecure_http`	`bool`	`false`	Consente HTTP in chiaro verso la TSA.

Services::tsaClient() restituisce null quando tsa.url è null o una stringa vuota. Quando viene selezionato un livello di firma che richiede una marca temporale, il firmatario collega automaticamente il client TSA.

Cache OCSP

Chiave	Tipo	Predefinito	Descrizione
`ocspCache.enabled`	`bool`	`true`	Abilita la cache delle risposte OCSP.
`ocspCache.ttl`	`int`	`86400`	TTL della cache in secondi.
`ocspCache.directory`	`string\|null`	`null`	Directory della cache; valore predefinito del motore quando è null.

Renderer HTML Chrome (NextPDF Artisan)

Chiave	Tipo	Predefinito	Descrizione
`artisan.chrome_binary`	`string\|null`	`null`	Percorso del binario Chrome/Chromium.
`artisan.render_timeout`	`int`	`30`	Timeout di rendering in secondi.
`artisan.default_css`	`string`	`''`	Foglio di stile predefinito.
`artisan.no_sandbox`	`bool`	`false`	Passa `--no-sandbox` a Chrome.
`artisan.max_html_size`	`int`	`5000000`	Dimensione massima dell’HTML in input in byte.

Il renderer Chrome viene configurato per il documento solo quando artisan.chrome_binary è impostato e nextpdf/artisan è installato.

Override tramite `.env`

BaseConfig risolve gli override d’ambiente per ogni proprietà. La chiave di lookup è il nome breve della classe in minuscolo, nextpdf, seguito dal percorso della proprietà. Le chiavi di array annidate si indirizzano tramite punti. Sono accettate sia la forma con i punti sia quella con i trattini bassi.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Il prefisso è il nome breve della classe in minuscolo. Rimane nextpdf anche se la classe è scritta NextPdf. È accettata anche la forma completa (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Override estendendo la classe

Per una configurazione tipizzata e sottoposta a controllo di versione, estendere la classe del pacchetto in app/Config/. CodeIgniter carica la classe dell’applicazione al posto della configurazione predefinita del pacchetto. Questo file dichiara una classe e non causa effetti collaterali. In questo modo resta allineato all’aspettativa PSR-1 secondo cui un file dichiara simboli oppure esegue logica con effetti collaterali, ma non entrambe le cose (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Casi limite e insidie

Sovrascrivere una singola chiave annidata con .env sovrascrive solo quella chiave; il resto dell’array mantiene i propri valori predefiniti.
.env contiene valori di tipo stringa. CodeIgniter converte true/false e le stringhe numeriche. Racchiudere tra virgolette i valori che devono rimanere stringhe letterali.
Estendere la classe con un array defaults parziale sostituisce l’intero array. Includere ogni chiave, come mostrato sopra.

Note sulla sicurezza

Mantenere i percorsi dei certificati e delle chiavi fuori dal controllo di versione. Fornirli tramite .env o un gestore di segreti. tsa.allow_insecure_http deve restare false in produzione. Vedere /integrations/codeigniter/security-and-operations/.

Conformità

Il file di estensione della configurazione dell’applicazione dichiara una classe e nessun effetto collaterale (PSR-1 §x1.x1.p3).

Contesto commerciale

Il core di NextPDF è Apache-2.0. Le chiavi signature.* e pdfa hanno effetto solo quando NextPDF Pro o Enterprise è installato. Il pacchetto CodeIgniter espone i corrispondenti metodi di servizio. Questi metodi restituiscono null finché non viene installato il corrispondente pacchetto Premium. Vedere </get-license/?intent=codeigniter-signing>.

Vedere anche

/integrations/codeigniter/install/ — installare il pacchetto.
/integrations/codeigniter/quickstart/ — primo PDF.
/integrations/codeigniter/production-usage/ — controller e job di coda collegati tramite DI.
/integrations/codeigniter/security-and-operations/ — hardening della configurazione di firma e percorsi.