Problemen met NextPDF op CodeIgniter 4 oplossen

In een oogopslag

Elk symptoom hieronder verwijst naar een geverifieerde oorzaak in de broncode van het pakket of het framework, met een concrete oplossing.

Detectie en resolutie

`Services::pdfDocument()` retourneert `null`

Wanneer CodeIgniter een service oplost, zoekt het in de gedetecteerde Config\Services-klassen naar een overeenkomende methode. Een null-resultaat betekent dat CodeIgniter de Services-klasse van het pakket niet heeft gedetecteerd.

Controleer deze oorzaken en oplossingen:

Automatische detectie is uitgeschakeld. De hosttoepassing heeft mogelijk Config\Modules::$discoverInComposer = false ingesteld. Voeg in dat geval nextpdf/codeigniter toe aan $composerPackages['only']. CodeIgniter doorzoekt Composer-pakketten alleen wanneer deze vlag true is.
De autoloader is verouderd. Composer koppelt het namespace-voorvoegsel NextPDF\CodeIgniter\ aan de bijbehorende basismap. Een verouderde classmap voorkomt dat de klasse wordt gevonden (PSR-4 §x1.x3). Voer composer dump-autoload uit.
De $aliases-lijst is ingekort. Detectie wordt alleen uitgevoerd voor de vermeldingen in Config\Modules::$aliases. Het pakket heeft services nodig en, voor helpers, registrars. Herstel beide vermeldingen.

`pdf()` of `pdf_document()` is niet gedefinieerd

De helpers worden langs twee routes geladen: de Composer-autoloadvermelding files van het pakket en de Registrar van het pakket. Een fout over een niet-gedefinieerde functie betekent dat de files-vermelding niet is geladen.

Voer composer dump-autoload uit om de files-autoloadlijst opnieuw op te bouwen.
Controleer of nextpdf/codeigniter voorkomt in vendor/composer/autoload_files.php.
Als je een tijdelijke oplossing nodig hebt, roep je Services::pdf(false) of Services::pdfDocument(false) rechtstreeks aan. De helpers zijn dunne wrappers rond deze aanroepen.

Configuratie

`.env`-overrides worden genegeerd

Bij het verwerken van een override gebruikt BaseConfig de korte klassenaam in kleine letters als voorvoegsel. Omdat de klasse NextPdf heet, is het voorvoegsel nextpdf. Het is niet nextPdf of NextPdf.

Gebruik nextpdf.fontsPath, niet nextPdf.fontsPath.
Gebruik voor een geneste sleutel een punt: nextpdf.signature.certificate.
De volledig gekwalificeerde vorm NextPDF\CodeIgniter\Config\NextPdf.fontsPath werkt ook.

Een hele config-array valt terug op de standaardwaarden

Wanneer je de NextPdf-klasse uitbreidt en een gedeeltelijke array toewijst, vervangt CodeIgniter de hele array. Geef elke sleutel op in de array die je overschrijft. Zie /integrations/codeigniter/configuration/ voor een voorbeeld met de volledige array.

Runtimefouten

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

Het lettertyperegister valideert mbstring en zlib eenmaal per proces. Het genereert deze fout met de naam van de ontbrekende extensie. Installeer of activeer de genoemde extensie in de PHP-runtime en start daarna de worker of de PHP FastCGI Process Manager (PHP-FPM)-pool opnieuw.

`RuntimeException: NextPdf fontsPath contains invalid characters`

Het lettertyperegister weigert een fontsPath die een stream-wrapper (://) of een null-byte bevat. Stel fontsPath in op een normaal bestandssysteempad. Laat het niet verwijzen naar een php://-, phar://- of vergelijkbaar verpakt pad.

Responsproblemen

De bestandsnaam ziet er verkeerd uit in de download

PdfResponse schoont bestandsnamen op. Dit is het geverifieerde gedrag:

Een lege bestandsnaam of een naam met alleen witruimte wordt document.pdf.
Aan een naam zonder de extensie .pdf (of .PDF) wordt .pdf toegevoegd. Een bestaande .PDF blijft ongewijzigd.
Een naam met niet-ASCII-tekens levert een ASCII-fallback en een RFC 5987-parameter filename*=UTF-8''… op, zodat moderne browsers de oorspronkelijke naam tonen. Dit is verwacht gedrag, geen fout.
Padscheidingstekens, null-bytes en carriage return/line feed (CR/LF) worden verwijderd.

De respons mist beveiligingsheaders

Elke PdfResponse bevat X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag en Referrer-Policy. Als ze bij de client ontbreken, verwijdert of overschrijft een proxy of de toepassing ze stroomafwaarts. Inspecteer de respons zowel voor als na je reverse proxy.

Wachtrij

`QueueException` bij het pushen van de taak

De wachtrij vergelijkt de gepushte taaknaam met de sleutels in Config\Queue::$jobHandlers en weigert elke naam die niet is geregistreerd. Registreer de taak onder een naamsleutel en push vervolgens die naam:

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

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

Het pushen van GeneratePdfJob::class als taaknaam mislukt. Het tweede argument is een naamsleutel, geen klassetekenreeks.

`InvalidArgumentException` vanuit de taak

De taak valideert zijn payload voordat er werk wordt uitgevoerd. In deze geverifieerde weigeringsgevallen worden deze berichtfragmenten geretourneerd:

Oorzaak	Berichtfragment
`builder` ontbreekt, is leeg of is geen tekenreeks	`non-empty static callable string`
`builder` buiten `App\PdfBuilders`	`not allowed`
`builder` komt overeen met het patroon, maar is niet aanroepbaar	`not a valid callable`
`outputPath` ontbreekt of is leeg	`non-empty string`
`outputPath` buiten `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` eindigt niet op `.pdf`	`must end with .pdf`

Pas de payload aan zodat de builder een statische callable App\PdfBuilders\<Class>::<method> is. Zorg dat het uitvoerpad binnen WRITEPATH/pdfs/ wordt opgelost met een .pdf-extensie.

`class … BaseJob not found`

Omdat codeigniter4/queue een uitsluitend voor ontwikkeling bedoelde afhankelijkheid van het pakket is, moet de toepassing die workers uitvoert deze rechtstreeks vereisen:

composer require codeigniter4/queue

Diagnostiek

composer show nextpdf/codeigniter — bevestig dat Composer het pakket heeft opgelost.
composer dump-autoload — bouw de detectie en de autoloadlijst van de helpers opnieuw op.
php spark routes — bevestig dat uw PDF-routes zijn geregistreerd.
Voor de snelste detectiecontrole gebruik je een controller die Services::pdfDocument(false) aanroept en controleert of het resultaat een Document is.

Conformiteit

Toewijzing van klasse aan pad — relevant voor detectiefouten (PSR-4 Autoloader §x1.x3).

Zie ook

/integrations/codeigniter/install/ — vereisten voor detectie.
/integrations/codeigniter/configuration/ — het .env-voorvoegsel en de regel voor het overschrijven van arrays.
/integrations/codeigniter/production-usage/ — correcte wachtrijregistratie.
/integrations/codeigniter/boot-and-discovery/ — de detectievolgorde.