NextPDF-Symfony-Integration im Überblick

Auf einen Blick

nextpdf/symfony ist das offizielle Symfony-7-Bundle für die NextPDF-Engine. Es verbindet die Engine mit dem Symfony-Container und stellt Ihnen eine Document-Factory bereit, die Sie in Ihre eigenen Services injizieren können. Außerdem bietet es HTTP-Response-Helfer und eine Möglichkeit, PDFs asynchron zu erzeugen, sodass die Arbeit im Hintergrund laufen kann.

Was das Bundle bereitstellt

NextPDF Symfony bindet die nextpdf/core-Engine als reguläres Bundle in eine Symfony-Anwendung ein. Es ergänzt die folgenden Bausteine, die jeweils gegen den Bundlequellcode in src/Symfony/ geprüft wurden:

• Ein Bundle-Einstiegspunkt — NextPDF\Symfony\NextPdfBundle erweitert die Symfony-Basisklasse Bundle und registriert einen Compiler-Pass.
• Eine Dependency-Injection-Erweiterung — NextPDF\Symfony\DependencyInjection\NextPdfExtension lädt die Servicedefinitionen, wandelt den Konfigurationsbaum in Containerparameter um und stellt den Konfigurationsalias nextpdf bereit.
• Ein typisierter Konfigurationsbaum — NextPDF\Symfony\DependencyInjection\Configuration definiert das nextpdf-Konfigurationsschema. Das Schema validiert Enum-Werte, setzt Standardwerte und nutzt %kernel.*%-Parameterplatzhalter.
• Eine injizierbare Document-Factory — NextPDF\Symfony\Service\PdfFactory erzeugt frische, vorkonfigurierte NextPDF\Core\Document-Instanzen. Sie ist das Symfony-Äquivalent einer statischen Fassade.
• HTTP-Response-Helfer — NextPDF\Symfony\Http\PdfResponse erstellt Inline-, Download- und Streaming-Responses mit einem festen Satz OWASP-konformer Security-Header.
• Ein asynchroner Erzeugungspfad — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler und NextPDF\Symfony\Message\PdfBuilderInterface integrieren sich in Symfony Messenger, sodass das PDF-Rendering in einem Worker laufen kann.
• Ein Erweiterungsdetektor zur Compile-Zeit — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass erkennt optionale NextPDF-Erweiterungen und registriert deren Services nur, wenn diese Erweiterungen vorhanden sind.

Container-Vertrag

Das Bundle registriert einen kleinen, stabilen Satz öffentlicher Container-Services. Der Document-Service nextpdf.document (mit Alias auf NextPDF\Contracts\PdfDocumentInterface und NextPDF\Core\Document) ist nicht geteilt: Jede Auflösung liefert ein eigenständiges, verwerfbares Dokument. Das entspricht dem PSR-11-Container-Vertrag, nach dem zwei aufeinanderfolgende get()-Aufrufe mit demselben Identifier je nach Containerkonfiguration unterschiedliche Werte zurückgeben können — siehe PSR-11 §1.1.2. Die nicht geteilte Bindung ist Absicht: Ein Dokument sammelt pro Rendervorgang Zustand an; daher verhindert eine neue Instanz pro Anfrage, dass Zustand in lang laufenden Workern zwischen Anfragen weitergetragen wird.

Die Font-Registry (NextPDF\Contracts\FontRegistryInterface) verhält sich umgekehrt: Sie ist ein geteiltes Singleton. Die Image-Registry trägt das kernel.reset-Tag, sodass ihr begrenzter Cache bei FrankenPHP und in Messenger-Workern zwischen Anfragen geleert wird. Die Konfigurationsseite dokumentiert die vollständige Service- und Alias-Tabelle.

Optionales Logging

Die Font- und Image-Registries akzeptieren einen optionalen PSR-3-Logger. Das Bundle bindet Psr\Log\LoggerInterface nur dann, wenn die Anwendung einen solchen bereitstellt (nullOnInvalid()). Logging ist daher ein optionaler Bestandteil und keine harte Abhängigkeit. Das entspricht dem PSR-3-Logger-Vertrag, nach dem ein Logger injizierbar und austauschbar ist (PSR-3).

Kernfunktionen versus optionale Funktionen

Das Bundle selbst ist Apache-2.0-Kernsoftware. Einige wenige Funktionen sind nur verfügbar, wenn Sie daneben ein optionales Paket installieren:

Funktion	Benötigt	Erkennung
PDF-Generierung, PdfFactory, PdfResponse	nur Kern	immer verfügbar
Asynchrone Erzeugung	symfony/messenger	Handler wird aktiv, wenn Messenger installiert ist
Chrome-CDP-HTML-Rendering	nextpdf/artisan	Prüfung per class_exists zur Compile-Zeit
PDF/A-Archivierung, digitale Signaturen	nextpdf/premium (installiert Pro)	Prüfung per class_exists zur Compile-Zeit

Wenn nextpdf/premium installiert ist, kann das Bundle eine Baseline-PAdES-B-B-Signaturkonfiguration anwenden. Höhere Signaturprofile gehören nicht zum Umfang der Dokumentation dieses Bundles. Die Editionsmatrix finden Sie in der NextPDF Premium-Dokumentation.

Wann Sie dieses Bundle einsetzen

Setzen Sie nextpdf/symfony ein, wenn Sie PDFs innerhalb einer Symfony-7-HTTP-Anwendung oder eines Workers erstellen. Das Bundle stellt Ihnen containerverwaltete Services, für Worker geeignete Registries und sichere Download-Responses bereit, sodass Sie die Engine nicht manuell verdrahten müssen. Wenn Sie nur eine einmalige Erzeugung in einem Skript benötigen, genügt das Kernpaket nextpdf/core.

Konformität

Jede normative Aussage auf dieser Seite ist über eine vollständige reference_id mit 64 Hexadezimalstellen aus dem freigegebenen SDO-Korpus verankert. Die Provenienz (Korpusmanifest, Retrieval-Transport) steht in _sidecars/rag-citations.yaml.

Spezifikation	Klausel	reference_id	Aussage
PSR-11	psr_11_container#1.1.2.p3.b		Container-get()-Rückgabewert-Vertrag
PSR-3	psr_3_logger#x3.p17		LoggerInterface als optionale Abhängigkeit

Kommerzieller Kontext

Digitale Signaturen und PDF/A-Archivierung werden verfügbar, wenn nextpdf/premium (Pro) zusammen mit dem Bundle installiert ist. Das ist eine optionale Pro-Funktion. Das hier dokumentierte Core-Bundle erfordert keine Codeänderung, um sie zu nutzen. Siehe </get-license/?intent=symfony-pro>.

Siehe auch

• /integrations/symfony/install/ — Installation und Registrierung des Bundles.
• /integrations/symfony/configuration/ — der vollständige nextpdf-Konfigurationsbaum und die Service-Tabelle.
• /integrations/symfony/quickstart/ — ein lauffähiger Controller sowie ein Async-Beispiel.
• /integrations/symfony/boot-and-discovery/ — wie Symfony das Bundle erkennt und bootet.
• /integrations/symfony/production-usage/ — Worker-Sicherheit, Streaming und Async-Muster.