Fehlerbehebung für NextPDF in CodeIgniter 4

Auf einen Blick

Jedes der folgenden Symptome verweist auf eine verifizierte Ursache im Quellcode des Pakets oder des Frameworks. Zu jedem Symptom gibt es zudem eine konkrete Lösung.

Discovery und Auflösung

`Services::pdfDocument()` liefert `null`

Zum Auflösen eines Service durchsucht CodeIgniter die per Discovery gefundenen Config\Services-Klassen nach einer passenden Methode. Ein Rückgabewert von null bedeutet, dass das Framework die Services-Klasse des Pakets nie per Discovery gefunden hat.

Die Ursachen und ihre Lösungen:

Die Auto-Discovery ist deaktiviert. Die Host-Anwendung setzt möglicherweise Config\Modules::$discoverInComposer = false. Falls ja, fügen Sie nextpdf/codeigniter zu $composerPackages['only'] hinzu. Discovery durchsucht Composer-Pakete nur, wenn dieses Flag true ist.
Der Autoloader ist veraltet. Composer ordnet das Namespace-Präfix NextPDF\CodeIgniter\ seinem Basisverzeichnis zu. Eine veraltete Classmap verbirgt die Klasse (PSR-4 §x1.x3). Führen Sie composer dump-autoload aus.
Die $aliases-Liste wurde gekürzt. Discovery läuft nur für die Einträge in Config\Modules::$aliases. Das Paket benötigt services und für die Helper zusätzlich registrars. Stellen Sie beide Einträge wieder her.

`pdf()` oder `pdf_document()` ist nicht definiert

Die Helper werden auf zwei Wegen registriert: über den Composer-files-Autoload-Eintrag des Pakets und über den Registrar des Pakets. Ein Fehler wegen einer nicht definierten Funktion bedeutet, dass der files-Eintrag nicht geladen wurde.

Führen Sie composer dump-autoload aus, um die files-Autoload-Liste neu aufzubauen.
Stellen Sie sicher, dass nextpdf/codeigniter in vendor/composer/autoload_files.php erscheint.
Rufen Sie als Workaround Services::pdf(false) oder Services::pdfDocument(false) direkt auf. Die Helper sind dünne Wrapper um diese Aufrufe.

Konfiguration

`.env`-Overrides werden ignoriert

Zum Auflösen eines Override verwendet BaseConfig den kurzen Klassennamen in Kleinbuchstaben als Präfix. Die Klasse heißt NextPdf, also lautet das Präfix nextpdf. Es lautet weder nextPdf noch NextPdf.

Verwenden Sie nextpdf.fontsPath, nicht nextPdf.fontsPath.
Adressieren Sie einen verschachtelten Schlüssel mit einem Punkt: nextpdf.signature.certificate.
Die voll qualifizierte Form NextPDF\CodeIgniter\Config\NextPdf.fontsPath funktioniert ebenfalls.

Ein ganzes Konfigurations-Array fällt auf die Standardwerte zurück

Wenn Sie die NextPdf-Klasse erweitern und ein partielles Array zuweisen, wird das gesamte Array ersetzt. Geben Sie daher jeden Schlüssel des Arrays an, das Sie überschreiben. Ein Beispiel für ein vollständiges Array finden Sie unter /integrations/codeigniter/configuration/.

Laufzeitfehler

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

Die Font-Registry validiert mbstring und zlib einmal pro Prozess. Sie löst diesen Fehler mit dem Namen der fehlenden Extension aus. Installieren oder aktivieren Sie die genannte Extension in der PHP-Laufzeitumgebung. Starten Sie anschließend den Worker oder den PHP-FPM-Pool neu.

`RuntimeException: NextPdf fontsPath contains invalid characters`

Die Font-Registry lehnt einen fontsPath ab, der einen Stream-Wrapper (://) oder ein Null-Byte enthält. Setzen Sie fontsPath auf einen reinen Dateisystempfad. Lassen Sie ihn nicht auf einen php://-, phar://- oder ähnlich gewrappten Pfad verweisen.

Probleme mit der Response

Der Dateiname sieht beim Download falsch aus

PdfResponse bereinigt Dateinamen. Das verifizierte Verhalten ist:

Ein leerer oder nur aus Leerzeichen bestehender Dateiname wird zu document.pdf.
An einen Namen ohne .pdf- (oder .PDF-)Erweiterung wird .pdf angehängt. Ein bereits vorhandenes .PDF bleibt unverändert erhalten.
Bei einem Namen mit Nicht-ASCII-Zeichen wird ein ASCII-Fallback und ein RFC 5987-Parameter filename*=UTF-8''… erzeugt, sodass moderne Browser den ursprünglichen Namen anzeigen. Das ist erwartet und kein Fehler.
Pfadtrenner, Null-Bytes und CR/LF werden entfernt.

In der Response fehlen Security-Header

Jede PdfResponse enthält X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag und Referrer-Policy. Fehlen sie beim Client, entfernt oder überschreibt ein Proxy oder die Anwendung sie später in der Kette. Prüfen Sie die Response sowohl vor als auch nach Ihrem Reverse-Proxy.

Queue

`QueueException` beim Pushen des Jobs

Die Queue vergleicht den Namen des gepushten Jobs mit den Schlüsseln von Config\Queue::$jobHandlers und lehnt jeden nicht registrierten Namen ab. Registrieren Sie den Job unter einem Namensschlüssel und pushen Sie anschließend diesen Namen:

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

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

Wenn Sie den Namen GeneratePdfJob::class als Jobnamen pushen, schlägt der Aufruf fehl. Das zweite Argument ist ein Namensschlüssel, kein Klassen-String.

`InvalidArgumentException` aus dem Job

Der Job validiert seinen Payload, bevor er Arbeit ausführt. Die verifizierten Ablehnungsfälle und ihre Meldungen sind:

Ursache	Meldungsfragment
`builder` fehlt, ist leer oder kein String	`non-empty static callable string`
`builder` außerhalb von `App\PdfBuilders`	`not allowed`
`builder` passt zum Muster, ist aber nicht aufrufbar	`not a valid callable`
`outputPath` fehlt oder ist leer	`non-empty string`
`outputPath` außerhalb von `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` endet nicht auf `.pdf`	`must end with .pdf`

Korrigieren Sie den Payload so, dass der Builder ein statisches Callable der Form App\PdfBuilders\<Class>::<method> ist. Stellen Sie sicher, dass sich der Ausgabepfad innerhalb von WRITEPATH/pdfs/ mit einer .pdf-Erweiterung auflöst.

`class … BaseJob not found`

codeigniter4/queue ist eine reine Entwicklungsabhängigkeit des Pakets. Die Anwendung, die Worker ausführt, muss sie selbst direkt anfordern:

composer require codeigniter4/queue

Diagnose

composer show nextpdf/codeigniter — bestätigen Sie, dass das Paket aufgelöst wurde.
composer dump-autoload — bauen Sie Discovery und Helper-Autoload neu auf.
php spark routes — bestätigen Sie, dass Ihre PDF-Routen registriert sind.
Am schnellsten prüfen Sie Discovery mit einem Controller, der Services::pdfDocument(false) aufruft und prüft, dass das Ergebnis ein Document ist.

Konformität

Klassen-zu-Pfad-Zuordnung — relevant bei Discovery-Fehlern (PSR-4-Autoloader §x1.x3).

Siehe auch

/integrations/codeigniter/install/ — Discovery-Anforderungen.
/integrations/codeigniter/configuration/ — das .env-Präfix und die Array-Override-Regel.
/integrations/codeigniter/production-usage/ — die korrekte Queue-Registrierung.
/integrations/codeigniter/boot-and-discovery/ — die Discovery-Sequenz.