Risoluzione dei problemi di NextPDF in CodeIgniter 4

In breve

Ogni sintomo descritto di seguito rimanda a una causa verificata nel sorgente del pacchetto o del framework ed è accompagnato da una soluzione concreta.

Discovery e risoluzione

`Services::pdfDocument()` restituisce `null`

Per risolvere un servizio, CodeIgniter analizza le classi Config\Services rilevate e cerca un metodo corrispondente. Un valore di ritorno null indica che il framework non ha mai rilevato la classe Services del pacchetto.

Le cause e le relative soluzioni:

Auto-discovery disabilitato. L’applicazione host potrebbe impostare Config\Modules::$discoverInComposer = false. In tal caso, aggiungere nextpdf/codeigniter a $composerPackages['only']. La discovery analizza i pacchetti Composer solo quando questo flag è true.
L’autoloader non è aggiornato. Composer mappa il prefisso del namespace NextPDF\CodeIgniter\ alla directory di base corrispondente. Una classmap non aggiornata nasconde la classe (PSR-4 §x1.x3). Eseguire composer dump-autoload.
L’elenco $aliases è stato ristretto. La discovery viene eseguita solo per le voci presenti in Config\Modules::$aliases. Il pacchetto richiede services e, per gli helper, anche registrars. Ripristinare entrambe le voci.

`pdf()` o `pdf_document()` non risultano definite

Gli helper vengono registrati attraverso due percorsi: la voce di autoload Composer files del pacchetto e il Registrar del pacchetto. Un errore di funzione non definita indica che la voce files non è stata caricata.

Eseguire composer dump-autoload per ricostruire l’elenco di autoload files.
Verificare che nextpdf/codeigniter compaia in vendor/composer/autoload_files.php.
In alternativa, chiamare direttamente Services::pdf(false) o Services::pdfDocument(false). Gli helper sono semplici wrapper di queste chiamate.

Configurazione

`.env`: gli override vengono ignorati

Per applicare un override, BaseConfig usa come prefisso il nome breve della classe in minuscolo. La classe è NextPdf, quindi il prefisso è nextpdf. Non è nextPdf e non è NextPdf.

Usare nextpdf.fontsPath, non nextPdf.fontsPath.
Indirizzare una chiave annidata con un punto: nextpdf.signature.certificate.
Funziona anche la forma completa NextPDF\CodeIgniter\Config\NextPdf.fontsPath.

Un intero array di configurazione torna ai valori predefiniti

Quando si estende la classe NextPdf e si assegna un array parziale, l’intero array viene sostituito. Fornire quindi ogni chiave dell’array di cui si esegue l’override. Per un esempio con array completo, vedere /integrations/codeigniter/configuration/.

Errori di runtime

`RuntimeException: NextPDF requires the ext-… PHP extension`

Il registro dei font convalida mbstring e zlib una volta per processo. Genera questo errore indicando il nome dell’estensione mancante. Installare o abilitare l’estensione indicata nel runtime PHP. Quindi riavviare il worker o il pool PHP-FPM.

`RuntimeException: NextPdf fontsPath contains invalid characters`

Il registro dei font rifiuta un fontsPath che contiene uno stream wrapper (://) o un byte null. Impostare fontsPath su un percorso semplice del filesystem. Non impostarlo su un percorso php://, phar:// o su un percorso analogo con wrapper.

Problemi di risposta

Il nome del file nel download appare errato

PdfResponse sanifica i nomi dei file. Il comportamento verificato è questo:

Un nome di file vuoto o composto solo da spazi diventa document.pdf.
A un nome privo di estensione .pdf (o .PDF) viene aggiunta .pdf. Un’estensione .PDF già presente viene conservata invariata.
Un nome non ASCII produce un fallback ASCII e un parametro RFC 5987 filename*=UTF-8''…, in modo che i browser moderni mostrino il nome originale. Questo comportamento è previsto, non è un bug.
I separatori di percorso, i byte null e i caratteri CR/LF vengono rimossi.

Intestazioni di sicurezza mancanti nella risposta

Ogni risposta PdfResponse include X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag e Referrer-Policy. Se il client non le riceve, un proxy o l’applicazione le sta rimuovendo o sovrascrivendo a valle. Esaminare la risposta sia prima sia dopo il reverse proxy.

Coda

`QueueException` durante l’accodamento del job

La coda confronta il nome del job accodato con le chiavi di Config\Queue::$jobHandlers e rifiuta qualsiasi nome non registrato. Registrare il job con una chiave nominale, quindi accodare quel nome:

public array $jobHandlers = ['generate-pdf' => GeneratePdfJob::class];

// dispatch
\service('queue')->push('pdf-queue', 'generate-pdf', [...]);

L’inserimento di GeneratePdfJob::class come nome del job non riesce. Il secondo argomento è una chiave nominale, non una stringa di classe.

`InvalidArgumentException` generata dal job

Il job convalida il proprio payload prima di eseguire qualsiasi operazione. I casi verificati in cui il payload viene rifiutato, con i relativi messaggi, sono i seguenti:

Causa	Frammento del messaggio
`builder` mancante, vuoto o non una stringa	`non-empty static callable string`
`builder` esterno a `App\PdfBuilders`	`not allowed`
`builder` corrisponde al pattern ma non è callable	`not a valid callable`
`outputPath` mancante o vuoto	`non-empty string`
`outputPath` esterno a `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` che non termina con `.pdf`	`must end with .pdf`

Correggere il payload in modo che il builder sia un callable statico App\PdfBuilders\<Class>::<method>. Assicurarsi che il percorso di output venga risolto all’interno di WRITEPATH/pdfs/ con un’estensione .pdf.

`class … BaseJob not found`

codeigniter4/queue è una dipendenza del pacchetto destinata esclusivamente allo sviluppo. L’applicazione che esegue i worker deve dichiararla direttamente:

composer require codeigniter4/queue

Diagnostica

composer show nextpdf/codeigniter — conferma che il pacchetto sia stato risolto.
composer dump-autoload — ricostruisce la discovery e l’autoload degli helper.
php spark routes — conferma che le route PDF siano registrate.
Il controllo più rapido per la discovery è un controller che chiama Services::pdfDocument(false) e verifica che il risultato sia un Document.

Conformità

Mappatura da classe a percorso — rilevante per gli errori di discovery (PSR-4 Autoloader §x1.x3).

Vedere anche

/integrations/codeigniter/install/ — requisiti della discovery.
/integrations/codeigniter/configuration/ — prefisso .env e regola di override dell’array.
/integrations/codeigniter/production-usage/ — registrazione corretta della coda.
/integrations/codeigniter/boot-and-discovery/ — sequenza di discovery.