Avvio e discovery di NextPDF in Symfony

In breve

Il kernel registra NextPdfBundle. L’estensione DI del bundle carica services.php e traduce l’albero di configurazione in parametri del container. Un compiler pass collega quindi le estensioni opzionali e il warmup dei font.

Come Symfony Flex rileva il bundle

Il file composer.json del bundle dichiara un’indicazione di registrazione automatica:

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

In un’applicazione Symfony Flex, questo aggiunge NextPDF\Symfony\NextPdfBundle a config/bundles.php per ogni ambiente (all). Senza Flex, aggiungere manualmente il bundle in config/bundles.php. Symfony documenta ufficialmente il modello di registrazione dei bundle (https://symfony.com/doc/current/bundles.html). Le classi del bundle vengono caricate automaticamente sotto il prefisso PSR-4 NextPDF\Symfony\, mappato su src/Symfony/. Un autoloader PSR-4 associa il prefisso del namespace a quella directory di base (PSR-4 §2).

Sequenza di avvio

Sequenza di avvio, verificata sul codice sorgente del bundle:

1. Il kernel registra i bundle. Kernel::registerBundles() legge config/bundles.php e istanzia NextPDF\Symfony\NextPdfBundle, che estende Symfony\Component\HttpKernel\Bundle\Bundle.
2. Build del bundle. NextPdfBundle::build() richiama il metodo della classe padre e poi registra un compiler pass: OptionalExtensionPass. NextPdfBundle::getPath() restituisce la radice del pacchetto.
3. Caricamento dell’estensione. L’estensione DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (alias nextpdf) esegue processConfiguration() rispetto a Configuration. Imposta i valori risolti come parametri del container nextpdf.*, quindi carica config/services.php tramite un PhpFileLoader.
4. Controllo delle estensioni obbligatorie. NextPdfExtension::load() termina verificando la presenza di ext-mbstring e ext-zlib; in caso contrario interrompe immediatamente l’esecuzione.
5. Esecuzione del compiler pass. Durante la compilazione del container, OptionalExtensionPass::process() configura i flag di disponibilità delle estensioni su PdfFactory, registra in modo condizionale il signer e il client TSA, quindi pianifica il warmup e il lock del font registry.
6. Container compilato e memorizzato nella cache. Symfony scrive il container compilato. cache:warmup esegue questo passaggio prima che arrivi traffico.

Compiler pass

Il bundle registra esattamente un pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, aggiunto in NextPdfBundle::build(). Viene eseguito nel gruppo di pass predefinito (before-optimization). Il pass svolge quattro passaggi. Ogni passaggio è protetto da una guardia, quindi non produce effetti quando i relativi input sono assenti:

• Flag delle estensioni — aggiunge le chiamate ai metodi setArtisanAvailable(...) e setProAvailable(...) alla definizione di PdfFactory. I valori derivano da verifiche class_exists eseguite in fase di compilazione per la browser factory di Artisan e la classe PDF/A di Pro.
• Registrazione del signer — quando nextpdf.signature è presente, enabled è true ed è impostato un certificato, registra una factory per le informazioni del certificato e un servizio signer per il profilo baseline B-B.
• Client TSA — quando nextpdf.tsa ha un URL, registra un servizio client TSA.
• Warmup dei font — quando nextpdf.preload_fonts non è vuoto, aggiunge le chiamate ai metodi warmup() e lock() alla definizione del font registry.

Binding del container

config/services.php definisce i servizi. Il servizio document nextpdf.document (con alias NextPDF\Contracts\PdfDocumentInterface e NextPDF\Core\Document) è non condiviso: ogni risoluzione restituisce una nuova istanza di documento, come PSR-11 consente esplicitamente — chiamate get() successive per uno stesso id possono restituire valori diversi (PSR-11 §1.1.2). Il font registry è condiviso e bloccato dopo il warmup. L’image registry è condiviso e contrassegnato con il tag kernel.reset. La tabella completa si trova in /integrations/symfony/configuration/.

Ordine di risoluzione della configurazione

1. Valori predefiniti incorporati da Configuration (getConfigTreeBuilder()).
2. Override dell’applicazione in config/packages/nextpdf.yaml, oltre agli override per ambiente in config/packages/<env>/.
3. Symfony risolve i placeholder dei parametri %kernel.*%. Ad esempio, fonts_path per impostazione predefinita vale %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() scrive il risultato combinato nei parametri del container nextpdf.* utilizzati da services.php e dal compiler pass.

I valori non validi falliscono nei passaggi 1–2 con un InvalidConfigurationException di Symfony.

Diagnostica

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

Il primo comando elenca i servizi registrati. Il secondo stampa la configurazione combinata. Il terzo ricostruisce il container e riesegue le verifiche delle estensioni in fase di compilazione.

Conformità

Ogni riga è un’affermazione normativa presente in questa pagina, ancorata a un reference_id completo da 64 cifre esadecimali del corpus SDO ad accesso controllato. La provenienza (manifest del corpus, trasporto di recupero) risiede in _sidecars/rag-citations.yaml.

Specifica	Clausola	reference_id	Affermazione
PSR-11	psr_11_container#1.1.2.p3.b		La risoluzione del container può variare a ogni chiamata
PSR-4	psr_4_autoload#x1.x2.p5		Mappatura dal prefisso del namespace alla directory di base

Vedere anche

• /integrations/symfony/integration/ — riferimento per il wiring end-to-end.
• /integrations/symfony/install/ — installazione e registrazione.
• /integrations/symfony/configuration/ — albero di configurazione completo e tabella dei servizi.
• /integrations/symfony/overview/ — riepilogo delle funzionalità.