Configurer le bundle Symfony NextPDF

En bref

Tout le comportement du bundle se configure sous la clé racine nextpdf dans config/packages/nextpdf.yaml. Chaque clé ayant une valeur par défaut, la configuration reste optionnelle. Cette page reflète exactement le contenu de Configuration.php.

Arbre de configuration

Le schéma est défini par NextPDF\Symfony\DependencyInjection\Configuration. Les valeurs invalides font échouer la construction du conteneur en levant une InvalidConfigurationException de Symfony.

Clés de premier niveau

Clé	Type	Valeur par défaut	Validation
page_format	énumération	A4	une de ces valeurs : A4, A3, A5, Letter, Legal, Tabloid
orientation	énumération	P	une de ces valeurs : P, L
unit	énumération	mm	une de ces valeurs : pt, mm, cm, in
pdfa	scalaire	null	une de ces valeurs : null, 4, 4e, 4f
fonts_path	scalaire	%kernel.project_dir%/resources/fonts	—
cache_path	scalaire	%kernel.cache_dir%/nextpdf	—
image_cache_mb	entier	50	minimum 0
font_cache_locking	booléen	true	—
preload_fonts	liste de chaînes	[]	—

icc_profile

Clé	Type	Valeur par défaut
icc_profile.rgb	scalaire	null
icc_profile.cmyk	scalaire	null

defaults

Cette section s’applique à chaque document produit par PdfFactory.

Clé	Type	Valeur par défaut
defaults.creator	scalaire	NextPDF
defaults.author	scalaire	(vide)
defaults.language	scalaire	en
defaults.margin_top	flottant	10.0
defaults.margin_right	flottant	10.0
defaults.margin_bottom	flottant	10.0
defaults.margin_left	flottant	10.0
defaults.font_family	scalaire	dejavusans
defaults.font_size	flottant	12.0
defaults.trim_box	variable	null
defaults.bleed_box	variable	null

PdfFactory lit creator, author et language dans cette section et les applique à chaque nouveau document. Les autres clés sont stockées comme paramètres de conteneur afin d’être consommées par le moteur.

artisan

Cette section ne prend effet que lorsque nextpdf/artisan est installé et détecté.

Clé	Type	Valeur par défaut
artisan.chrome_binary	scalaire	null
artisan.render_timeout	entier	30
artisan.default_css	scalaire	(vide)
artisan.no_sandbox	booléen	false
artisan.max_html_size	entier	5000000

signature

Cette section ne prend effet que lorsque nextpdf/premium est installé. Lorsque le bundle et le niveau Pro sont tous deux présents, la configuration de signature prise en charge correspond au profil de base B-B. Le nœud level accepte les valeurs de chaîne listées ci-dessous afin d’assurer la compatibilité de schéma avec la famille plus large de configurations NextPDF. La capacité de signature fournie par ce bundle est B-B. Les profils au-delà de B-B sont documentés séparément dans la documentation NextPDF Premium et ne sont pas revendiqués ici.

Clé	Type	Valeur par défaut	Validation
signature.enabled	booléen	false	—
signature.certificate	scalaire	null	—
signature.private_key	scalaire	null	—
signature.password	scalaire	(vide)	—
signature.extra_certs	liste de chaînes	[]	—
signature.level	énumération	B-B	valeurs acceptées : B-B, B-T, B-LT, B-LTA (B-B livré ; B-T/B-LT/B-LTA sont des valeurs de compatibilité de schéma, pas une capacité Pro livrée)

La passe de compilation enregistre un service de signataire uniquement lorsque signature.enabled vaut true et que signature.certificate est défini ; sinon, la section est inerte.

tsa

Configuration du client Time Stamp Authority, utilisée par la signature Pro quand elle est configurée.

Clé	Type	Valeur par défaut
tsa.url	scalaire	null
tsa.username	scalaire	(vide)
tsa.password	scalaire	(vide)
tsa.cert	scalaire	null
tsa.key	scalaire	null
tsa.timeout	entier	30
tsa.allow_insecure_http	booléen	false
tsa.pinned_public_keys	liste de chaînes	[]
tsa.warn_on_key_rotation	booléen	true

Un service client TSA est enregistré uniquement lorsque tsa.url est défini.

ocsp_cache

Clé	Type	Valeur par défaut
ocsp_cache.enabled	booléen	true
ocsp_cache.ttl	entier	86400
ocsp_cache.directory	scalaire	null

messenger

Paramètres de génération asynchrone, utilisés lorsque symfony/messenger est installé.

Clé	Type	Valeur par défaut
messenger.transport	scalaire	async
messenger.timeout	entier	120
messenger.retries	entier	3

Configuration de référence

Voici un fichier de configuration montrant chaque section avec ses valeurs par défaut :

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Services de conteneur et alias

Le bundle charge ses définitions de services depuis config/services.php. Le tableau ci-dessous reflète exactement ce fichier.

ID de service	Partagé	Public	Notes
NextPDF\Typography\FontRegistry	oui	—	construit à partir de nextpdf.fonts_path ; logger PSR-3 optionnel
NextPDF\Contracts\FontRegistryInterface	(alias)	oui	alias de FontRegistry
NextPDF\Graphics\ImageRegistry	oui	—	cache LRU borné ; tagué kernel.reset (reset)
NextPDF\Core\DocumentFactory	oui	—	partage les deux registres
NextPDF\Contracts\DocumentFactoryInterface	(alias)	oui	alias de DocumentFactory
NextPDF\Symfony\Service\PdfFactory	oui	oui	lit les defaults, pdfa, artisan comme paramètres
NextPDF\Contracts\PdfDocumentInterface	non	oui	fabrique [PdfFactory, create]
NextPDF\Core\Document	(alias)	—	alias de PdfDocumentInterface
nextpdf.document	(alias)	oui	alias de PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	oui	assistant sans état

Le bundle enregistre également les liaisons de contrats EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) uniquement lorsque les classes d’implémentation Premium correspondantes existent. Chaque liaison est enregistrée en mode non partagé afin que les appelants reçoivent une instance neuve. L’état d’analyse propre à chaque appel ne fuit jamais d’une requête à l’autre.

Services partagés et non partagés

nextpdf.document (et ses alias) est non partagé : chaque résolution du conteneur renvoie un document distinct. Selon PSR-11, un conteneur est autorisé à renvoyer une valeur différente lors d’appels get() successifs avec le même identifiant — PSR-11 §1.1.2. Le registre de polices est partagé et, après le préchauffage, verrouillé. Les données structurelles de police sont donc analysées une seule fois par processus et ne peuvent pas être modifiées en cours de requête.

Les services FontRegistry et ImageRegistry acceptent un Psr\Log\LoggerInterface optionnel, lié avec nullOnInvalid(). Le logger est un collaborateur optionnel et interchangeable, conformément au contrat de logger PSR-3 (PSR-3).

Autowiring

PdfFactory, PdfResponse, l’interface de fabrique de documents et l’interface de registre de polices sont publics. Tu peux les récupérer depuis le conteneur ou les typer dans des contrôleurs et services autowirés. L’injection par constructeur de NextPDF\Symfony\Service\PdfFactory est le point d’entrée recommandé.

Cas limites et pièges

• pdfa défini sans Pro — la valeur est stockée, mais ignorée. PdfFactory n’applique PDF/A que lorsque l’extension Pro est détectée à la compilation.
• image_cache_mb: 0 — est une valeur valide et désactive le cache LRU d’images. Les valeurs négatives sont rejetées au moment de la construction.
• signature.enabled: true sans signature.certificate — le service de signataire n’est pas enregistré ; la configuration reste inerte sans avertissement, par conception.
• Espaces réservés %kernel.*% — les valeurs par défaut de fonts_path et cache_path utilisent des paramètres de conteneur Symfony ; remplace-les par des chemins absolus uniquement lorsque le chemin littéral est requis.

Conformité

Chaque ligne correspond à une affirmation normative de cette page, ancrée à un reference_id complet de 64 caractères hexadécimaux et issu du corpus SDO sous contrôle d’accès. 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		get() peut renvoyer des valeurs différentes à chaque résolution
PSR-3	psr_3_logger#x3.p17		Collaborateur LoggerInterface optionnel

Contexte commercial

Les sections signature et tsa ne prennent effet que lorsque nextpdf/premium (Pro) est installé. Il s’agit d’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/overview/ — résumé des capacités.
• /integrations/symfony/production-usage/ — sécurité des workers et schémas asynchrones.
• /integrations/symfony/boot-and-discovery/ — comment la configuration est résolue pendant le démarrage.