Configurer le package NextPDF pour Laravel

En bref

config/nextpdf.php est publié avec php artisan vendor:publish --tag=nextpdf-config. Chaque clé dispose d’une variable d’environnement de secours et d’une valeur par défaut codée en dur. Cette page documente chaque clé exactement telle qu’elle apparaît dans le fichier config/nextpdf.php du package.

Installation

php artisan vendor:publish --tag=nextpdf-config

Le provider fusionne aussi les valeurs par défaut du package sous la clé de configuration nextpdf pendant register(). Les clés non définies utilisent donc les valeurs ci-dessous, même avant la publication.

Vue d’ensemble conceptuelle

La plupart des variables d’environnement acceptent soit un nom NEXTPDF_*, soit un nom historique TCPDF_*. L’ancien préfixe reste pris en charge pendant la période de transition documentée dans UPGRADE.md ; les nouveaux déploiements doivent utiliser la forme NEXTPDF_*. Le fichier de configuration résout les valeurs dans cet ordre : variable d’environnement → valeur du fichier publié → valeur par défaut du package.

Surface d’API — clés de configuration

Mise en page du document

Clé	Env (principale)	Défaut	Effet
page_format	NEXTPDF_PAGE_FORMAT	A4	Format de page par défaut (A4, A3, A5, Letter, Legal, Tabloid)
orientation	NEXTPDF_ORIENTATION	P	Portrait (P) ou paysage (L)
unit	NEXTPDF_UNIT	mm	Unité de mesure (pt, mm, cm, in)
defaults.creator	NEXTPDF_CREATOR	NextPDF	Métadonnée du créateur du document ; appliquée au binding PdfDocumentInterface du document
defaults.author	NEXTPDF_AUTHOR	(vide)	Métadonnée d’auteur ; appliquée uniquement lorsqu’elle n’est pas vide
defaults.language	NEXTPDF_LANG	en	Langue du document ; appliquée au binding du document
defaults.margin_top / _right / _bottom / _left	—	10	Marges par défaut
defaults.font_family	—	dejavusans	Famille de police par défaut
defaults.font_size	—	12	Taille de police par défaut
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] en points, ou null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] en points, ou null

Le provider applique defaults.creator, defaults.language et, lorsqu’il est défini, defaults.author à chaque document fraîchement résolu. La branche defaults.author est ignorée lorsque la valeur est vide.

Archivage et couleur

Clé	Env (principale)	Défaut	Effet
pdfa	NEXTPDF_PDFA	null	Niveau d’archivage PDF/A (null, 4, 4e, 4f). Une valeur non nulle active PDF/A sur le binding du document et nécessite nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Répertoire des polices TrueType supplémentaires ; pilote le chemin de recherche du registre des polices
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Répertoire de cache pour les polices analysées et les fichiers temporaires
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Chemin du profil ICC RGB ; requis pour PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Profil ICC CMYK facultatif pour les workflows d’impression
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Utilise flock sur le cache des polices pour éviter toute corruption lorsque des workers de file concurrents écrivent

Définir pdfa sur une valeur non nulle nécessite le niveau Premium. Sans nextpdf/premium, résoudre le binding du document lorsque pdfa est défini déclenche une erreur class-not-found pour le type de version PDF/A. Cette page ne décrit pas le comportement d’archivage Premium ; voir la documentation Premium.

Mémoire des workers (runtimes à longue durée de vie)

Clé	Env (principale)	Défaut	Effet
preload_fonts	—	[]	Liste des chemins absolus vers les fichiers de police analysés au démarrage du worker. Le registre des polices est verrouillé après le préchauffage
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Budget du cache d’images LRU en Mo. 0 désactive le cache. Le provider n’impose aucune limite supérieure

Le provider n’impose aucune limite supérieure au budget du cache d’images. Applique une limite de mémoire du conteneur ou php.inimemory_limit pour le borner. Le fichier de configuration recommande un maximum pratique de 256 Mo.

Signature numérique (Premium)

Clé	Env (principale)	Défaut	Effet
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Lorsque false (ou si le certificat est vide), SignerInterface se résout en null
signature.certificate	NEXTPDF_SIGN_CERT	null	Chemin du certificat de signature
signature.private_key	NEXTPDF_SIGN_KEY	null	Chemin de la clé privée
signature.password	NEXTPDF_SIGN_PASSWORD	(vide)	Phrase secrète de la clé
signature.extra_certs	—	[]	Chemins des certificats de CA intermédiaires
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Niveau baseline PAdES transmis au signataire

Le package Core documenté ici ne fournit pas de signataire concret ; le binding SignerInterface se résout en null jusqu’à ce que nextpdf/premium fournisse un signataire. Avec Premium, level: B-B produit une signature baseline PAdES B-B. Les niveaux baseline PAdES supérieurs dépendent d’une autorité d’horodatage configurée et d’une capacité Premium ; cette page ne documente pas ces niveaux.

Autorité d’horodatage

Clé	Env (principale)	Défaut	Effet
tsa.url	NEXTPDF_TSA_URL	null	Point de terminaison TSA. Lorsqu’il est vide, TsaClient se résout en null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(empty)	Identifiants HTTP de la TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Certificat / clé client pour le mTLS avec la TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Délai d’expiration HTTP en secondes pour le client PSR-18
tsa.pinned_public_keys	—	[]	Empreintes SPKI SHA-256 en Base64 (RFC 7469). Une valeur vide désactive l’épinglage
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Émet un avertissement lorsque la TSA présente un SPKI non épinglé
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Autorise le HTTP en clair vers la TSA. À laisser à false en production

Cache des réponses OCSP

Clé	Env (principale)	Défaut	Effet
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Met en cache les réponses OCSP pendant la validation
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL du cache en secondes
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Répertoire du cache ; null conserve le cache uniquement en mémoire

File d’attente

Clé	Env (principale)	Défaut	Effet
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Connexion de la file d’attente ; null utilise la connexion par défaut
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Nom de la file vers laquelle GeneratePdfJob est poussé
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Délai d’expiration par job en secondes

Renderer Chrome CDP (extension Artisan)

Clé	Env (principale)	Défaut	Effet
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	valeur d’env ou non définie	Chemin vers le binaire Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Délai d’expiration du rendu en secondes
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(vide)	CSS par défaut injecté dans le HTML rendu
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Désactive la sandbox de Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Taille maximale de l’entrée HTML en octets

La section artisan est appliquée au binding du document uniquement si une classe browser-factory Chrome est présente (l’extension nextpdf/artisan). Lorsqu’elle est absente, la section est ignorée.

Exemple de code — Production

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Cas limites & pièges

• signature.enabled = true avec un signature.certificate vide résout toujours SignerInterface en null ; les deux doivent être définis.
• tsa.url = null force TsaClient à null, même si d’autres clés tsa.* sont renseignées.
• signature.level = null retombe sur PAdES B-B au niveau du signataire.
• image_cache_mb défini à null (et non 0) retombe sur la valeur par défaut de 50 Mo ; 0 désactive explicitement le cache.
• Les anciennes variables d’environnement TCPDF_* restent prises en charge en lecture, mais elles sont dépréciées ; migre vers NEXTPDF_*.

Performance

La lecture de la config correspond à un accès tableau en O(1). preload_fonts échange une analyse unique en O(f) au démarrage du worker contre une latence plus faible à la première requête. Un image_cache_mb plus grand réduit le décodage répété des images au prix d’une mémoire résidente plus élevée pour le processus.

Notes de sécurité

tsa.allow_insecure_http affaiblit la confiance dans l’horodatage et doit rester false en production. Les URL de la TSA ne doivent provenir que d’une configuration de confiance ; si elles sont exposées via une surface d’administration, applique un pare-feu de sortie ou une politique DNS pour limiter les risques de falsification de requête. Voir /integrations/laravel/security-and-operations/.

Conformité

Aucune norme normative ne régit le format du fichier de configuration ; toutes les clés sont vérifiées par rapport au config/nextpdf.php du package à la révision documentée. La sémantique des niveaux de signature est régie par Premium et hors du périmètre de cette page Core.

Contexte commercial

Les sections signature et tsa pilotent la signature Premium lorsque nextpdf/premium est installé. Il s’agit d’une capacité Enterprise facultative ; le package Core documenté ici n’a besoin d’aucune modification de code pour l’adopter. Voir https://nextpdf.dev/get-license/?intent=laravel-signing.

Voir aussi

• /integrations/laravel/install/ — publier le fichier de configuration
• /integrations/laravel/production-usage/ — configuration appliquée dans un contrôleur réel
• /integrations/laravel/security-and-operations/ — durcir les réglages de la TSA et de la file d’attente
• /integrations/laravel/boot-and-discovery/ — le binding piloté par chaque clé