Fehlerbehebung für das NextPDF Symfony-Bundle

Auf einen Blick

Die meisten Probleme lassen sich einem von vier Bereichen zuordnen: Erkennung, Konfigurationsvalidierung, Container-Verdrahtung oder Messenger-Routing. Jeder Abschnitt verknüpft ein Symptom mit dem im Bundle-Quellcode verifizierten Verhalten und nennt anschließend einen Konsolenbefehl, mit dem Sie die Behebung bestätigen.

Das Bundle ist nicht registriert

Symptom: PdfFactory kann nicht per Autowiring aufgelöst werden, oder debug:container nextpdf liefert keine Treffer.

Ursache: Das Bundle wurde nicht in config/bundles.php eingetragen. Entweder wurde Flex nicht ausgeführt, oder die Anwendung verwendet Flex nicht.

Lösung:

php bin/console debug:container nextpdf

Wenn die Ausgabe leer ist, fügen Sie das Bundle manuell hinzu:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

Der Hinweis zur automatischen Registrierung steht in der composer.json des Bundles unter extra.symfony.bundles. Er greift nur bei Anwendungen, die Flex unterstützen.

Der Bootvorgang scheitert an einer fehlenden PHP-Erweiterung

Symptom: Der Kernel wirft beim Bootvorgang eine RuntimeException, in der ext-mbstring oder ext-zlib genannt wird.

Ursache: Das ist der bewusst eingebaute Fail-Fast-Schutz des Bundles, NextPdfExtension::guardRequiredExtensions(), und kein Defekt.

Lösung: Aktivieren Sie die genannte Erweiterung in php.ini und starten Sie die Laufzeitumgebung neu. Bestätigen Sie dies mit:

php -m | grep -E 'mbstring|zlib'

Die Konfiguration wird zur Build-Zeit abgelehnt

Symptom: Während cache:clear oder cache:warmup tritt eine Symfony\Component\Config\Definition\Exception\InvalidConfigurationException auf.

Ursache: Ein Wert liegt außerhalb des Schemas. Die folgenden Einschränkungen stammen aus Configuration.php:

page_format muss einer der Werte A4, A3, A5, Letter, Legal, Tabloid sein.
orientation muss P oder L sein.
unit muss einer der Werte pt, mm, cm, in sein.
pdfa muss null, 4, 4e oder 4f sein.
image_cache_mb muss >= 0 sein.

Lösung: Geben Sie die zusammengeführte Konfiguration aus und korrigieren Sie anschließend den fehlerhaften Schlüssel:

php bin/console debug:config nextpdf

PDF/A oder Signierung bleibt wirkungslos

Symptom: pdfa oder der Abschnitt signature ist gesetzt, aber die Ausgabe bleibt ein gewöhnliches PDF.

Ursache: Diese Funktionen erfordern nextpdf/premium. PdfFactory wendet PDF/A nur an, wenn die Pro-Erweiterung zur Compile-Zeit erkannt wird. Der Compiler-Pass registriert einen Signierer nur, wenn signature.enabled wahr ist und signature.certificate gesetzt ist.

Lösung: Stellen Sie sicher, dass Premium installiert ist und der Signierer-Dienst existiert:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Wenn Premium fehlt, speichert das Bundle die Konfiguration, lässt sie aber bewusst ohne Wirkung. Die dokumentierte Signierfunktion des Bundles mit Pro ist das Basisprofil B-B. Die Dokumentation von NextPDF Premium behandelt Profile über B-B hinaus.

Das Chrome-Rendering zeigt keine Wirkung

Symptom: Die artisan-Konfiguration wird ignoriert.

Ursache: Das Chrome-CDP-Rendering erfordert nextpdf/artisan. Der Compiler-Pass prüft dies zur Compile-Zeit mit class_exists. Fehlt die Erweiterung, wird der Renderer nicht verdrahtet.

Lösung:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

Die Prüfung läuft während der Container-Kompilierung. Führen Sie daher nach der Installation der Erweiterung erneut cache:clear aus.

Der Messenger-Handler wird nie aufgerufen

Symptom: GeneratePdfMessage wird versendet, aber es wird kein PDF geschrieben.

Ursachen und Lösungen:

Nachricht nicht geroutet — fügen Sie einen Routing-Eintrag hinzu, der NextPDF\Symfony\Message\GeneratePdfMessage in config/packages/messenger.yaml einem Transport zuordnet, und starten Sie anschließend einen Worker (php bin/console messenger:consume <transport>).
Builder fehlt im Locator — der Handler holt den Builder über seine Klassennamen-ID aus einem PSR-11-Locator. Ein Container-Bezeichner ist eine Zeichenkette, die einen Eintrag eindeutig identifiziert (PSR-11 §1.1.2). Wenn der Locator die Builder-Klasse nicht registriert hat, wirft der Handler eine RuntimeException mit dem Hinweis, dass der konfigurierte Builder PdfBuilderInterface implementieren muss. Registrieren Sie den Builder und referenzieren Sie ihn dann aus dem Locator.

Prüfen Sie Routing und Locator:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

Nachricht wird beim Versand mit InvalidArgumentException abgelehnt

Symptom: Das Erstellen von GeneratePdfMessage wirft eine InvalidArgumentException.

Ursache: Das Data Transfer Object (DTO) der Nachricht validiert seine Eingaben. Die verifizierten Ablehnungsregeln lauten:

ein leerer Ausgabepfad oder einer, der ein Null-Byte enthält;
ein Stream-Wrapper-Schema (zum Beispiel php://...);
ein ..-Path-Traversal-Segment (mit POSIX- oder Windows-Trennzeichen);
ein Ausgabepfad, der nicht auf .pdf endet (ohne Berücksichtigung der Groß-/Kleinschreibung);
eine builderClass, die kein syntaktisch gültiger Klassenname ist.

Lösung: Übergeben Sie einen absoluten Dateisystempfad, der auf .pdf endet, sowie einen echten voll qualifizierten Builder-Klassennamen.

Ein Dokument enthält veraltete Daten

Symptom: Ein generiertes PDF enthält Inhalte aus einem vorherigen Request.

Ursache: Eine Document-Instanz wurde in einem langlaufenden Worker über mehrere Requests hinweg gehalten. Genau deshalb ist der Dokumentdienst nicht geteilt.

Lösung: Rufen Sie PdfFactory::create() innerhalb der Request-bezogenen Methode auf. Speichern Sie das zurückgegebene Dokument niemals auf einem geteilten Dienst.

Referenz der Diagnosebefehle

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Konformität

Jede Zeile enthält eine normative Aussage dieser Seite und ist an einer vollständigen 64-stelligen Hex-reference_id aus dem gated SDO-Korpus verankert. Die Provenance für Korpus-Manifest und Abruf-Transport steht in _sidecars/rag-citations.yaml.

Spezifikation	Klausel	reference_id	Aussage
PSR-11	`psr_11_container#1.1.2.p4`		Bezeichnervertrag für Container-has()/get()

Siehe auch

/integrations/symfony/install/ — Installation und Registrierung.
/integrations/symfony/configuration/ — vollständiges Schema und Einschränkungen.
/integrations/symfony/boot-and-discovery/ — Erkennungs- und Bootsequenz.
/integrations/symfony/security-and-operations/ — Sicherheits-Header und Pfadvalidierung.