Problemen oplossen met het NextPDF Laravel-package

In een oogopslag

Gebruik deze pagina om zichtbare package-storingen te koppelen aan hun geverifieerde grondoorzaak op broncodeniveau. Elke vermelding geeft je het symptoom, de oorzaak en de oplossing.

Installatie

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Conceptueel overzicht

De meeste gemelde problemen vallen in vijf groepen: discovery, container-resolutie, ondertekening, queue-jobs en bestandsnamen in Hypertext Transfer Protocol (HTTP)-responses. Het package faalt bewust expliciet. Optionele functies die niet zijn geconfigureerd, geven null terug, en onveilige invoer veroorzaakt getypeerde excepties. Het symptoom wijst meestal direct naar de oorzaak.

API-oppervlak — symptoom naar oorzaak

Discovery en boot

Symptoom	Geverifieerde oorzaak	Oplossing
Provider is niet geregistreerd na installatie	De applicatie schakelt discovery uit met extra.laravel.dont-discover	Verwijder het package uit dont-discover, of registreer NextPdfServiceProvider handmatig in bootstrap/providers.php
config('nextpdf') is leeg	De configuratie is niet samengevoegd omdat er geen aangekondigde binding is geresolveerd (deferred provider)	Resolveer een willekeurige provides()-entry, of controleer discovery met php artisan package:discover --ansi
config/nextpdf.php niet aangemaakt door publish	Verkeerde publish-tag	Gebruik exact de tag: php artisan vendor:publish --tag=nextpdf-config
RuntimeException: “NextPDF requires the ext-mbstring/ext-zlib PHP extension”	Een vereiste Hypertext Preprocessor (PHP)-extensie ontbreekt tijdens runtime	Installeer of activeer mbstring en zlib in php.ini

Container-resolutie

Symptoom	Geverifieerde oorzaak	Oplossing
app(SignerInterface::class) retourneert null	Ondertekening is uitgeschakeld of het certificaat is leeg in nextpdf.signature	Stel signature.enabled = true en een geldige signature.certificate in; installeer nextpdf/premium om de concrete signer te leveren
app(TsaClient::class) retourneert null	nextpdf.tsa.url is leeg	Configureer tsa.url (en credentials/pins indien nodig)
Class-not-found voor een PDF/A-versietype	nextpdf.pdfa is non-null maar nextpdf/premium is niet geïnstalleerd	Installeer nextpdf/premium, of zet pdfa terug op null
Class-not-found bij het resolveren van een e-invoice-contract	Bindings zijn geregistreerd, maar de Premium-concretes ontbreken	Installeer nextpdf/premium; e-invoice-contracten worden lazy geresolveerd en falen pas bij de eerste resolve zonder Premium
Hetzelfde document wordt over twee logische bewerkingen heen gemuteerd	De document-binding is een factory; je hebt één geresolveerde instantie hergebruikt	Resolveer per document een nieuwe PdfDocumentInterface

Een container zonder entry werpt een not-found-exceptie op get() (PHP Standard Recommendation 11 (PSR-11) §1.1.2). De e-invoice-contracten zijn bound, dus de has() van de container retourneert true. De ontbrekende Premium-concrete veroorzaakt de fout op het moment van constructie, niet de container zelf.

Queue-jobs

Symptoom	Geverifieerde oorzaak	Oplossing
InvalidArgumentException: Path traversal sequences are not allowed	Het uitvoerpad bevat een ..-segment	Gebruik een absoluut pad zonder traversal binnen je opslagmap
InvalidArgumentException: Stream wrappers are not allowed	Het pad gebruikt een schema zoals php://	Gebruik een gewoon bestandssysteempad
InvalidArgumentException: Output path contains null bytes	Het pad bevat een \0-byte	Saneer het pad vóór dispatch
InvalidArgumentException: Output path must end with .pdf extension	Het pad eindigt niet op .pdf (hoofdletterongevoelig)	Gebruik een .pdf- (of .PDF-)suffix
Job draait maar bestand is leeg of onjuist	De builder-closure heeft het geconfigureerde document niet geretourneerd	Retourneer het document uit de builder; de job slaat de geretourneerde waarde op
Job gebruikt de verkeerde queue of timeout	nextpdf.queue.* is niet ingesteld zoals verwacht	Stel queue.queue, queue.connection en queue.timeout in; tries en backoff vereisen subclassing

Padcontroles draaien binnen handle() op de worker, dus een onjuist pad faalt tijdens de uitvoering, niet bij dispatch. Dit is opzettelijk: de worker valideert de geserialiseerde queue-payload op de plek waar die payload wordt verbruikt.

HTTP-responses en bestandsnamen

Symptoom	Geverifieerde oorzaak	Oplossing
Downloadbestandsnaam is onverwacht document.pdf	Je hebt een lege bestandsnaam doorgegeven; de factory gebruikt de standaard	Geef een niet-lege bestandsnaam door
Bestandsnaam is pad of speciale tekens kwijt	De bestandsnaam-sanitizer verwijdert padscheidingstekens, stuurtekens en null-bytes	Geef alleen de basisbestandsnaam door; deze hardening is verwacht gedrag
Niet-ASCII-bestandsnaam toont mojibake in sommige clients	De response stuurt Request for Comments 5987 (RFC 5987) filename*= uit voor niet-ASCII-namen; oude clients lezen de ASCII-fallback	Verwacht gedrag; geef een ASCII-veilige naam op als de naam in een legacy-client exact moet overeenkomen
Gestreamde response heeft geen Content-Length	Gestreamde responses laten Content-Length opzettelijk weg (chunked output)	Verwacht gedrag; gebruik de niet-gestreamde inline()/download() als een length-header vereist is

Codevoorbeeld — diagnostiek

# Confirm the provider is discovered
php artisan package:discover --ansi

# Inspect merged configuration
php artisan tinker --execute="dump(config('nextpdf.queue'));"

resource: src/Laravel/NextPdfServiceProvider.php (null-check pattern)

<?php

declare(strict_types=1);

use NextPDF\Contracts\SignerInterface;

$signer = app(SignerInterface::class);

if ($signer === null) {
    // Signing not configured, or nextpdf/premium not installed.
    // Continue without a signature, or fail with a clear message.
}

Randgevallen en valkuilen

• Met de deferred provider kan een verse installatie “kapot” lijken tot de eerste relevante resolve. Zie de vermelding van het package door package:discover als het successignaal.
• Wanneer image_cache_mb = null, valt het package terug op 50 MB; alleen 0 schakelt de cache uit. Bij een melding “cache schakelt niet uit” was meestal null gebruikt.
• Wanneer signature.level = null, valt het package stilzwijgend terug op PDF Advanced Electronic Signatures (PAdES) B-B. Bij een melding “onverwachte B-B” was het niveau meestal niet geconfigureerd.

Prestaties

Als de eerste requests op een langlopende worker traag zijn, parseert het lettertyperegister on demand. Stel nextpdf.preload_fonts in zodat de warmup eenmalig draait wanneer de worker start. Zie /integrations/laravel/configuration/ en /integrations/laravel/boot-and-discovery/ voor details.

Beveiligingsnotities

De pad- en bestandsnaamafwijzingen zijn beveiligingsmaatregelen, geen bugs. Omzeil ze niet door vooraf te decoderen of de controles te versoepelen. Leid bestandsuitvoer in plaats daarvan via een gecontroleerd opslagpad. Zie /integrations/laravel/security-and-operations/.

Conformiteit

Bewering	Bron	Clausule	reference_id
Ontbrekende container-entry werpt not-found op get()	PSR-11 Container	§1.1.2

Zie ook

• /integrations/laravel/install/ — discovery- en publish-stappen
• /integrations/laravel/configuration/ — elke sleutel en de bijbehorende standaardwaarde
• /integrations/laravel/production-usage/ — dependency injection (DI)- en queue-patronen
• /integrations/laravel/security-and-operations/ — waarom de padcontroles bestaan