Dépannage du bundle Symfony NextPDF

En bref

La plupart des problèmes relèvent de quatre catégories : découverte, validation de la configuration, câblage du conteneur ou routage Messenger. Chaque section ci-dessous associe un symptôme au contrôle effectué dans le code source du bundle, puis fournit une commande console pour confirmer le correctif.

Le bundle n’est pas enregistré

Symptôme : PdfFactory ne peut pas être auto-câblé, ou debug:container nextpdf ne retourne rien.

Cause : le bundle n’a pas été ajouté à config/bundles.php. Soit Flex ne s’est pas exécuté, soit l’application n’utilise pas Flex.

Résolution :

php bin/console debug:container nextpdf

Si la sortie est vide, ajoute le bundle manuellement :

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

La déclaration d’enregistrement automatique se trouve dans le composer.json du bundle, sous extra.symfony.bundles. Elle ne s’applique qu’aux applications où Flex est activé.

Le démarrage échoue à cause d’une extension PHP manquante

Symptôme : le kernel lève une RuntimeException mentionnant ext-mbstring ou ext-zlib au démarrage.

Cause : c’est le garde-fou fail-fast volontaire du bundle, NextPdfExtension::guardRequiredExtensions(). Ce n’est pas un défaut.

Résolution : active l’extension indiquée dans php.ini et redémarre le runtime. Confirme avec :

php -m | grep -E 'mbstring|zlib'

La configuration est rejetée au moment du build

Symptôme : une Symfony\Component\Config\Definition\Exception\InvalidConfigurationException survient pendant cache:clear ou cache:warmup.

Cause : une valeur ne respecte pas le schéma. Ces contraintes proviennent de Configuration.php :

• page_format doit valoir l’une des valeurs A4, A3, A5, Letter, Legal, Tabloid.
• orientation doit valoir P ou L.
• unit doit valoir l’une des valeurs pt, mm, cm, in.
• pdfa doit valoir null, 4, 4e ou 4f.
• image_cache_mb doit être >= 0.

Résolution : affiche la configuration fusionnée, puis corrige la clé fautive :

php bin/console debug:config nextpdf

PDF/A ou la signature n’a aucun effet

Symptôme : pdfa ou la section signature est définie, mais la sortie est un PDF ordinaire.

Cause : ces fonctionnalités nécessitent nextpdf/premium. PdfFactory applique PDF/A uniquement lorsque l’extension Pro est détectée au moment de la compilation. La passe du compilateur enregistre un signataire uniquement quand signature.enabled vaut true et que signature.certificate est défini.

Résolution : vérifie que Premium est installé et que le service signataire existe :

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Si Premium est absent, le bundle stocke la configuration mais la laisse inerte par conception. La fonctionnalité de signature documentée du bundle avec Pro correspond au profil B-B de référence. La documentation NextPDF Premium couvre les profils au-delà de B-B.

Le rendu Chrome ne produit rien

Symptôme : la configuration artisan est ignorée.

Cause : le rendu Chrome CDP nécessite nextpdf/artisan. La passe du compilateur le recherche avec class_exists au moment de la compilation. Si l’extension est absente, le moteur de rendu n’est jamais câblé.

Résolution :

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

La détection s’exécute pendant la compilation du conteneur. Après avoir installé l’extension, lance donc un nouveau cache:clear.

Le handler Messenger n’est jamais appelé

Symptôme : GeneratePdfMessage est dispatché, mais aucun PDF n’est écrit.

Causes et résolutions :

• Message non routé — ajoute une entrée de routage qui associe NextPDF\Symfony\Message\GeneratePdfMessage à un transport dans config/packages/messenger.yaml, puis lance un worker (php bin/console messenger:consume <transport>).
• Builder absent du locator — le handler récupère le builder depuis un locator PSR-11 via son identifiant de type class-string. Un identifiant de conteneur est une chaîne qui identifie de façon unique une entrée (PSR-11 §1.1.2). Si la classe du builder n’est pas enregistrée dans le locator, le handler lève une RuntimeException indiquant que le builder configuré doit implémenter PdfBuilderInterface. Enregistre le builder, puis référence-le depuis le locator.

Inspecte le routage et le locator :

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

Un message est rejeté au dispatch avec une InvalidArgumentException

Symptôme : la construction de GeneratePdfMessage lève une InvalidArgumentException.

Cause : l’objet de transfert de données (DTO) du message valide ses entrées. Les règles de rejet appliquées sont les suivantes :

• un chemin de sortie vide ou contenant un octet nul ;
• un schéma de wrapper de flux (par exemple php://...) ;
• un segment de traversée de répertoires .. (séparateurs POSIX ou Windows) ;
• un chemin de sortie qui ne se termine pas par .pdf (insensible à la casse) ;
• un builderClass qui n’est pas un nom de classe syntaxiquement valide.

Résolution : passe un chemin absolu du système de fichiers se terminant par .pdf et un véritable nom de classe de builder pleinement qualifié.

Un document contient des données obsolètes

Symptôme : un PDF généré inclut du contenu d’une requête précédente.

Cause : une instance de Document a été conservée d’une requête à l’autre dans un worker à exécution longue. Le service de document est non partagé précisément pour éviter cela.

Résolution : appelle PdfFactory::create() à l’intérieur de la méthode qui traite la requête. Ne stocke jamais le document retourné sur un service partagé.

Référence des commandes de diagnostic

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Conformité

Chaque ligne correspond à une revendication normative formulée sur cette page, rattachée à un reference_id complet de 64 caractères hexadécimaux issu du corpus SDO à accès contrôlé. La provenance, qui couvre le manifeste du corpus et le transport de récupération, se trouve dans _sidecars/rag-citations.yaml.

Spécification	Clause	reference_id	Revendication
PSR-11	psr_11_container#1.1.2.p4		Contrat d’identifiant has()/get() du conteneur

Voir aussi

• /integrations/symfony/install/ — installation et enregistrement.
• /integrations/symfony/configuration/ — schéma complet et contraintes.
• /integrations/symfony/boot-and-discovery/ — séquence de découverte et de démarrage.
• /integrations/symfony/security-and-operations/ — en-têtes de sécurité et validation des chemins.