Dépannage NextPDF sur CodeIgniter 4

En bref

Chaque symptôme ci-dessous renvoie à une cause vérifiée dans le code source du package ou du framework, avec un correctif concret associé.

Découverte et résolution

`Services::pdfDocument()` renvoie `null`

Quand CodeIgniter résout un service, il parcourt les classes Config\Services découvertes à la recherche d’une méthode correspondante. Un retour null indique que le framework n’a jamais découvert la classe Services du package.

Causes possibles et correctifs :

L’auto-découverte est désactivée. L’application hôte peut définir Config\Modules::$discoverInComposer = false. Dans ce cas, ajoute nextpdf/codeigniter à $composerPackages['only']. La découverte ne parcourt les packages Composer que lorsque cet indicateur vaut true.
L’autoloader n’est pas à jour. Composer mappe le préfixe de namespace NextPDF\CodeIgniter\ vers son répertoire de base. Une classmap obsolète masque la classe (PSR-4 §x1.x3). Exécute composer dump-autoload.
La liste $aliases a été réduite. La découverte ne s’exécute que pour les entrées de Config\Modules::$aliases. Le package a besoin de services, ainsi que de registrars pour les helpers. Restaure les deux entrées.

`pdf()` ou `pdf_document()` n’est pas défini

Les helpers sont enregistrés par deux mécanismes : l’entrée d’autoload Composer files du package et le Registrar du package. Une erreur de fonction non définie signifie que l’entrée files n’a pas été chargée.

Exécute composer dump-autoload pour reconstruire la liste d’autoload files.
Confirme que nextpdf/codeigniter apparaît dans vendor/composer/autoload_files.php.
Comme solution de contournement, appelle directement Services::pdf(false) ou Services::pdfDocument(false). Les helpers ne sont que de fines surcouches autour de ces appels.

Configuration

Les surcharges `.env` sont ignorées

Pour résoudre une surcharge, BaseConfig utilise le nom court de la classe en minuscules comme préfixe. La classe est NextPdf, donc le préfixe est nextpdf. Le préfixe n’est ni nextPdf ni NextPdf.

Utilise nextpdf.fontsPath, pas nextPdf.fontsPath.
Utilise un point pour cibler une clé imbriquée : nextpdf.signature.certificate.
La forme qualifiée complète NextPDF\CodeIgniter\Config\NextPdf.fontsPath fonctionne aussi.

Un tableau de configuration entier revient aux valeurs par défaut

Quand tu étends la classe NextPdf et que tu affectes un tableau partiel, le tableau entier est remplacé. Fournis donc chaque clé du tableau que tu surcharges. Pour un exemple de tableau complet, voir /integrations/codeigniter/configuration/.

Erreurs d’exécution

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

Le registre de polices vérifie mbstring et zlib une fois par processus. Il lève cette erreur avec le nom de l’extension manquante. Installe ou active l’extension nommée dans l’environnement PHP d’exécution. Puis redémarre le worker ou le pool PHP-FPM.

`RuntimeException: NextPdf fontsPath contains invalid characters`

Le registre de polices rejette un fontsPath qui contient un wrapper de flux (://) ou un octet nul. Définis fontsPath sur un simple chemin du système de fichiers. Ne le fais pas pointer vers php://, phar:// ni vers un chemin similaire reposant sur un wrapper.

Problèmes de réponse

Le nom de fichier semble incorrect dans le téléchargement

PdfResponse assainit les noms de fichiers. Le comportement vérifié est le suivant :

Un nom de fichier vide ou constitué uniquement d’espaces devient document.pdf.
Un nom sans extension .pdf (ou .PDF) reçoit l’extension .pdf. Un .PDF existant est conservé tel quel.
Un nom non-ASCII donne lieu à un repli ASCII et à un paramètre RFC 5987 filename*=UTF-8''…, de sorte que les navigateurs modernes affichent le nom d’origine. C’est le comportement attendu, pas un bug.
Les séparateurs de chemin, les octets nuls et les CR/LF sont supprimés.

Des en-têtes de sécurité manquent dans la réponse

Chaque réponse PdfResponse inclut X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag et Referrer-Policy. S’ils sont absents côté client, un proxy ou l’application les supprime ou les écrase en aval. Inspecte la réponse avant et après ton reverse proxy.

File d’attente

`QueueException` lors du push du job

La file d’attente compare le nom du job poussé aux clés de Config\Queue::$jobHandlers, et rejette tout nom qui n’est pas enregistré. Enregistre le job sous une clé de nom, puis pousse cette clé :

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

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

Pousser GeneratePdfJob::class comme nom de job échoue. Le second argument est une clé de nom, pas une chaîne de classe.

`InvalidArgumentException` provenant du job

Le job valide sa charge utile avant d’effectuer le moindre travail. Les cas de rejet vérifiés et leurs messages sont les suivants :

Cause	Fragment de message
`builder` manquant, vide ou pas une chaîne	`non-empty static callable string`
`builder` en dehors de `App\PdfBuilders`	`not allowed`
`builder` correspond au motif mais n’est pas appelable	`not a valid callable`
`outputPath` manquant ou vide	`non-empty string`
`outputPath` hors de `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` ne se terminant pas par `.pdf`	`must end with .pdf`

Corrige la charge utile pour que le builder soit un callable statique App\PdfBuilders\<Class>::<method>. Assure-toi que le chemin de sortie se résout à l’intérieur de WRITEPATH/pdfs/ avec une extension .pdf.

`class … BaseJob not found`

codeigniter4/queue est une dépendance du package réservée au développement. L’application qui exécute des workers doit l’ajouter directement à ses dépendances :

composer require codeigniter4/queue

Diagnostics

composer show nextpdf/codeigniter — confirme que le package est résolu.
composer dump-autoload — reconstruit la découverte et l’autoload des helpers.
php spark routes — confirme que tes routes PDF sont enregistrées.
Le test de découverte le plus rapide consiste à utiliser un contrôleur qui appelle Services::pdfDocument(false) et vérifie que le résultat est un Document.

Conformité

Correspondance classe-chemin — pertinente pour les échecs de découverte (PSR-4 Autoloader §x1.x3).

Voir aussi

/integrations/codeigniter/install/ — prérequis de découverte.
/integrations/codeigniter/configuration/ — le préfixe .env et la règle de surcharge de tableau.
/integrations/codeigniter/production-usage/ — enregistrement correct de la file d’attente.
/integrations/codeigniter/boot-and-discovery/ — la séquence de découverte.