NextPDF-Boot und -Discovery in Symfony

Auf einen Blick

Der Kernel registriert NextPdfBundle. Die DI-Extension des Bundles lädt services.php und überführt den Konfigurationsbaum in Container-Parameter. Anschließend verdrahtet ein einzelner Compiler-Pass optionale Erweiterungen und den Font-Warmup.

Wie Symfony Flex das Bundle erfasst

Die composer.json des Bundles deklariert einen Hinweis zur automatischen Registrierung:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

In einer Symfony-Flex-Anwendung fügt dies NextPDF\Symfony\NextPdfBundle für jede Umgebung (all) zu config/bundles.php hinzu. Ohne Flex fügen Sie das Bundle manuell in config/bundles.php ein. Symfony dokumentiert das Modell der Bundle-Registrierung offiziell (https://symfony.com/doc/current/bundles.html). Die Klassen des Bundles werden unter dem PSR-4-Präfix NextPDF\Symfony\ automatisch geladen, das auf src/Symfony/ abgebildet ist. Ein PSR-4-Autoloader bildet das Namespace-Präfix auf dieses Basisverzeichnis ab (PSR-4 §2).

Boot-Sequenz

Die Boot-Sequenz, anhand des Bundle-Quellcodes geprüft:

1. Der Kernel registriert die Bundles. Kernel::registerBundles() liest config/bundles.php und instanziiert NextPDF\Symfony\NextPdfBundle, das Symfony\Component\HttpKernel\Bundle\Bundle erweitert.
2. Bundle-Build. NextPdfBundle::build() ruft die Elternmethode auf und registriert dann einen einzelnen Compiler-Pass: OptionalExtensionPass. NextPdfBundle::getPath() gibt das Paket-Root zurück.
3. Laden der Extension. Die DI-Extension NextPDF\Symfony\DependencyInjection\NextPdfExtension (Alias nextpdf) führt processConfiguration() mit Configuration aus. Sie setzt die aufgelösten Werte als nextpdf.*-Container-Parameter und lädt anschließend config/services.php über einen PhpFileLoader.
4. Schutz für erforderliche Erweiterungen. NextPdfExtension::load() stellt am Ende sicher, dass ext-mbstring und ext-zlib vorhanden sind, und bricht andernfalls sofort ab.
5. Der Compiler-Pass läuft. Während der Container-Kompilierung konfiguriert OptionalExtensionPass::process() die Verfügbarkeits-Flags der Erweiterungen an PdfFactory, registriert bei Bedarf den Signer und den TSA-Client und plant Warmup und Lock der Font-Registry.
6. Der Container wird kompiliert und zwischengespeichert. Symfony schreibt den kompilierten Container. cache:warmup führt diesen Schritt vor dem Traffic aus.

Compiler-Passes

Das Bundle registriert genau einen Pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, der in NextPdfBundle::build() hinzugefügt wird. Er läuft in der Standard-Pass-Gruppe (vor der Optimierung). Der Pass führt vier Schritte aus. Jeder Schritt ist abgesichert, sodass er bei fehlenden Eingaben zu einem No-op wird:

• Erweiterungs-Flags — fügt die Methodenaufrufe setArtisanAvailable(...) und setProAvailable(...) zur Definition von PdfFactory hinzu. Die Werte stammen aus class_exists-Prüfungen zur Compile-Zeit für die Artisan-Browser-Factory und die Pro-PDF/A-Klasse.
• Registrierung des Signers — wenn nextpdf.signature vorhanden ist, enabled true ist und ein Zertifikat gesetzt ist, werden eine Factory für Zertifikatsinformationen und ein Signer-Dienst für das Baseline-Profil B-B registriert.
• TSA-Client — wenn nextpdf.tsa eine URL hat, wird ein TSA-Client-Dienst registriert.
• Font-Warmup — wenn nextpdf.preload_fonts nicht leer ist, werden der Definition der Font-Registry die Methodenaufrufe warmup() und lock() hinzugefügt.

Container-Bindings

config/services.php definiert die Dienste. Der Dokument-Dienst nextpdf.document (mit Alias auf NextPDF\Contracts\PdfDocumentInterface und NextPDF\Core\Document) ist non-shared: Jede Auflösung gibt ein frisches Dokument zurück, was PSR-11 ausdrücklich erlaubt — aufeinanderfolgende get()-Aufrufe für eine ID dürfen unterschiedliche Werte zurückgeben (PSR-11 §1.1.2). Die Font-Registry ist shared und wird nach dem Warmup gesperrt. Die Image-Registry ist shared und mit kernel.reset getaggt. Die vollständige Tabelle finden Sie unter /integrations/symfony/configuration/.

Auflösungsreihenfolge der Konfiguration

1. Integrierte Standardwerte aus Configuration (getConfigTreeBuilder()).
2. Anwendungs-Overrides in config/packages/nextpdf.yaml und Umgebungs-Overrides unter config/packages/<env>/.
3. Symfony löst die %kernel.*%-Parameter-Platzhalter auf. fonts_path ist zum Beispiel standardmäßig %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() schreibt das zusammengeführte Ergebnis in die nextpdf.*-Container-Parameter, die von services.php und dem Compiler-Pass konsumiert werden.

Ungültige Werte schlagen in Schritt 1–2 mit einer Symfony InvalidConfigurationException fehl.

Diagnostik

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

Der erste Befehl listet die registrierten Dienste auf. Der zweite gibt die zusammengeführte Konfiguration aus. Der dritte baut den Container neu auf und führt die Erweiterungsprüfungen zur Compile-Zeit erneut aus.

Konformität

Jede Zeile ist eine normative Aussage auf dieser Seite, festgelegt durch eine vollständige, 64-stellige hexadezimale reference_id aus dem gated SDO-Korpus. Die Provenance (Korpus-Manifest, Retrieval-Transport) liegt in _sidecars/rag-citations.yaml.

Spezifikation	Klausel	reference_id	Aussage
PSR-11	psr_11_container#1.1.2.p3.b		Die Container-Auflösung kann pro Aufruf abweichen
PSR-4	psr_4_autoload#x1.x2.p5		Abbildung von Namespace-Präfix auf Basisverzeichnis

Siehe auch

• /integrations/symfony/integration/ — End-to-End-Referenz für die Verdrahtung.
• /integrations/symfony/install/ — Installation und Registrierung.
• /integrations/symfony/configuration/ — vollständiger Konfigurationsbaum und Diensttabelle.
• /integrations/symfony/overview/ — Überblick über die Funktionen.