Présentation de l’intégration NextPDF pour Symfony

En un coup d’œil

nextpdf/symfony est le bundle Symfony 7 officiel du moteur NextPDF. Il relie le moteur au conteneur Symfony et te fournit une fabrique de documents injectable dans tes propres services. Il embarque aussi des helpers de réponse HTTP et un chemin de génération PDF asynchrone, afin que le travail puisse s’exécuter en arrière-plan.

Ce que fournit le bundle

NextPDF Symfony intègre le moteur nextpdf/core à une application Symfony sous la forme d’un bundle standard. Il ajoute les briques ci-dessous, toutes vérifiées à partir du code source du bundle dans src/Symfony/ :

Un point d’entrée de bundle — NextPDF\Symfony\NextPdfBundle étend la classe de base Bundle de Symfony et enregistre une passe de compilation.
Une extension d’injection de dépendances — NextPDF\Symfony\DependencyInjection\NextPdfExtension charge les définitions de services, transforme l’arbre de configuration en paramètres du conteneur et expose l’alias de configuration nextpdf.
Un arbre de configuration typé — NextPDF\Symfony\DependencyInjection\Configuration définit le schéma de configuration nextpdf. Le schéma valide les valeurs d’énumération, applique des valeurs par défaut et utilise des espaces réservés de paramètres %kernel.*%.
Une fabrique de documents injectable — NextPDF\Symfony\Service\PdfFactory produit des instances NextPDF\Core\Document nouvelles et préconfigurées. C’est l’équivalent Symfony d’une façade statique.
Des helpers de réponse HTTP — NextPDF\Symfony\Http\PdfResponse construit des réponses en ligne, en téléchargement et en flux, avec un ensemble fixe d’en-têtes de sécurité alignés sur l’OWASP.
Un chemin de génération asynchrone — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler et NextPDF\Symfony\Message\PdfBuilderInterface s’intègrent à Symfony Messenger pour permettre au rendu PDF de s’exécuter sur un worker.
Un détecteur d’extensions à la compilation — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass détecte les extensions NextPDF optionnelles et n’enregistre leurs services que lorsque ces extensions sont présentes.

Contrat du conteneur

Le bundle enregistre un petit ensemble stable de services publics du conteneur. Le service de document nextpdf.document (aliasé vers NextPDF\Contracts\PdfDocumentInterface et NextPDF\Core\Document) n’est pas partagé : chaque résolution renvoie un document distinct et jetable. Cela correspond au contrat de conteneur PSR-11, selon lequel deux appels successifs à get() avec le même identifiant peuvent renvoyer des valeurs différentes selon la configuration du conteneur — voir PSR-11 §1.1.2. Cette liaison non partagée est délibérée : un document accumule un état propre à chaque rendu, donc une instance neuve par requête empêche l’état de fuiter d’une requête à l’autre dans les workers à longue durée de vie.

Le registre de polices (NextPDF\Contracts\FontRegistryInterface) fonctionne à l’inverse : c’est un singleton partagé. Le registre d’images porte le tag kernel.reset, donc son cache borné est vidé entre les requêtes sous FrankenPHP et dans les workers Messenger. La page de configuration documente la table complète des services et des alias.

Journalisation optionnelle

Les registres de polices et d’images acceptent un logger PSR-3 optionnel. Le bundle ne lie Psr\Log\LoggerInterface que lorsque l’application en fournit un (nullOnInvalid()). La journalisation est donc un collaborateur optionnel plutôt qu’une dépendance stricte. Cela reste cohérent avec le contrat de logger PSR-3, selon lequel un logger est un collaborateur injecté et interchangeable (PSR-3).

Capacités du cœur ou optionnelles

Le bundle lui-même est un logiciel cœur sous Apache-2.0. Quelques capacités ne sont disponibles que lorsque tu installes un package optionnel à côté :

Capacité	Nécessite	Détection
Génération de PDF, `PdfFactory`, `PdfResponse`	cœur uniquement	toujours disponible
Génération asynchrone	`symfony/messenger`	le handler s’active quand Messenger est installé
Rendu HTML via Chrome CDP	`nextpdf/artisan`	sonde `class_exists` à la compilation
Archivage PDF/A, signatures numériques	`nextpdf/premium` (installe Pro)	sonde `class_exists` à la compilation

Lorsque nextpdf/premium est installé, le bundle peut appliquer une configuration de signature PAdES de référence B-B. Les profils de signature supérieurs sortent du périmètre de la documentation de ce bundle. Pour la matrice des éditions, consulte la documentation NextPDF Premium.

Quand utiliser ce bundle

Utilise nextpdf/symfony lorsque tu construis des PDF dans une application HTTP Symfony 7 ou un worker. Le bundle te fournit des services gérés par le conteneur, des registres sûrs pour les workers et des réponses de téléchargement sécurisées, pour que tu n’aies pas à câbler le moteur à la main. Si tu as seulement besoin d’une génération ponctuelle dans un script, le package cœur nextpdf/core seul suffit.

Conformité

Chaque ligne est une affirmation normative formulée sur cette page, ancré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éc	Clause	reference_id	Affirmation
PSR-11	`psr_11_container#1.1.2.p3.b`		Contrat de valeur de retour de get() du conteneur
PSR-3	`psr_3_logger#x3.p17`		Dépendance optionnelle à LoggerInterface

Contexte commercial

Les signatures numériques et l’archivage PDF/A deviennent disponibles lorsque nextpdf/premium (Pro) est installé à côté du bundle. C’est une capacité Pro optionnelle. Le bundle Core documenté ici n’exige aucune modification de code pour l’adopter. Voir </get-license/?intent=symfony-pro>.

Voir aussi

/integrations/symfony/install/ — installe et enregistre le bundle.
/integrations/symfony/configuration/ — l’arbre de configuration nextpdf complet et la table des services.
/integrations/symfony/quickstart/ — un contrôleur exécutable et un exemple asynchrone.
/integrations/symfony/boot-and-discovery/ — comment Symfony découvre et démarre le bundle.
/integrations/symfony/production-usage/ — sûreté des workers, streaming et patterns asynchrones.