Démarrage et découverte de NextPDF dans Symfony

En bref

Le kernel enregistre NextPdfBundle. L’extension DI du bundle charge services.php, puis expose l’arbre de configuration résolu sous forme de paramètres du conteneur. Un seul compiler pass câble ensuite les extensions optionnelles et le préchauffage des polices.

Comment Symfony Flex enregistre le bundle

Le composer.json du bundle déclare un indice d’enregistrement automatique :

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

Dans une application Symfony Flex, cela ajoute NextPDF\Symfony\NextPdfBundle à config/bundles.php pour tous les environnements (all). Sans Flex, ajoute le bundle manuellement dans config/bundles.php. Symfony documente officiellement le modèle d’enregistrement des bundles (https://symfony.com/doc/current/bundles.html). Les classes du bundle sont chargées automatiquement sous le préfixe PSR-4 NextPDF\Symfony\, mappé vers src/Symfony/. Un autoloader PSR-4 associe le préfixe de l’espace de noms à ce répertoire de base (PSR-4 §2).

Séquence de démarrage

La séquence de démarrage, vérifiée dans le code source du bundle :

1. Le kernel enregistre les bundles. Kernel::registerBundles() lit config/bundles.php et instancie NextPDF\Symfony\NextPdfBundle, qui étend Symfony\Component\HttpKernel\Bundle\Bundle.
2. Construction du bundle. NextPdfBundle::build() appelle le parent puis enregistre un seul compiler pass : OptionalExtensionPass. NextPdfBundle::getPath() renvoie la racine du package.
3. Chargement de l’extension. L’extension DI NextPDF\Symfony\DependencyInjection\NextPdfExtension (alias nextpdf) appelle processConfiguration() avec Configuration. Elle écrit les valeurs résolues dans les paramètres du conteneur nextpdf.*, puis charge config/services.php via un PhpFileLoader.
4. Vérification des extensions requises. NextPdfExtension::load() se termine en vérifiant que ext-mbstring et ext-zlib sont présentes, et échoue rapidement sinon.
5. Exécution du compiler pass. Pendant la compilation du conteneur, OptionalExtensionPass::process() configure les indicateurs de disponibilité des extensions sur PdfFactory, enregistre conditionnellement le signataire et le client TSA, et planifie le préchauffage et le verrouillage du registre des polices.
6. Conteneur compilé et mis en cache. Symfony écrit le conteneur compilé. cache:warmup effectue cette étape avant que l’application ne serve du trafic.

Compiler passes

Le bundle enregistre exactement un pass, NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass, ajouté dans NextPdfBundle::build(). Il s’exécute dans le groupe de passes par défaut (avant optimisation). Le pass effectue quatre étapes. Chaque étape est protégée par une garde, de sorte qu’elle ne fait rien quand ses entrées sont absentes :

• Indicateurs d’extension — ajoute les appels de méthode setArtisanAvailable(...) et setProAvailable(...) à la définition de PdfFactory. Les valeurs proviennent de sondes class_exists effectuées à la compilation pour la factory de navigateur Artisan et la classe PDF/A Pro.
• Enregistrement du signataire — quand nextpdf.signature est présent, que enabled vaut true et qu’un certificat est défini, enregistre une factory d’informations sur le certificat et un service de signataire pour le profil de base B-B.
• Client TSA — quand nextpdf.tsa possède une URL, enregistre un service client TSA.
• Préchauffage des polices — quand nextpdf.preload_fonts n’est pas vide, ajoute les appels de méthode warmup() et lock() à la définition du registre des polices.

Liaisons du conteneur

config/services.php définit les services. Le service de document nextpdf.document (aliasé sur NextPDF\Contracts\PdfDocumentInterface et NextPDF\Core\Document) est non partagé : chaque résolution renvoie un nouveau document, ce que PSR-11 autorise explicitement : des appels successifs à get() pour un même id peuvent renvoyer des valeurs différentes (PSR-11 §1.1.2). Le registre des polices est partagé et verrouillé après le préchauffage. Le registre d’images est partagé et tagué kernel.reset. Le tableau complet se trouve dans /integrations/symfony/configuration/.

Ordre de résolution de la configuration

1. Valeurs par défaut intégrées issues de Configuration (getConfigTreeBuilder()).
2. Surcharges applicatives dans config/packages/nextpdf.yaml, ainsi que les surcharges d’environnement sous config/packages/<env>/.
3. Symfony résout les espaces réservés de paramètres %kernel.*%. Par exemple, fonts_path vaut par défaut %kernel.project_dir%/resources/fonts.
4. NextPdfExtension::load() écrit le résultat fusionné dans les paramètres du conteneur nextpdf.*, que services.php et le compiler pass consomment.

Les valeurs invalides provoquent un échec aux étapes 1–2 avec une InvalidConfigurationException Symfony.

Diagnostics

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

La première commande liste les services enregistrés. La deuxième affiche la configuration fusionnée. La troisième reconstruit le conteneur et relance les sondes d’extension effectuées à la compilation.

Conformité

Chaque ligne correspond à une affirmation normative de cette page, épinglée à un reference_id complet de 64 caractères hexadécimaux issu du corpus SDO sous accès contrôlé. La provenance (manifeste du corpus, transport de récupération) se trouve dans _sidecars/rag-citations.yaml.

Spécification	Clause	reference_id	Affirmation
PSR-11	psr_11_container#1.1.2.p3.b		La résolution du conteneur peut différer d’un appel à l’autre
PSR-4	psr_4_autoload#x1.x2.p5		Mappage du préfixe d’espace de noms vers le répertoire de base

Voir aussi

• /integrations/symfony/integration/ — référence du câblage de bout en bout.
• /integrations/symfony/install/ — installation et enregistrement.
• /integrations/symfony/configuration/ — arbre de configuration complet et tableau des services.
• /integrations/symfony/overview/ — résumé des capacités.