Configurer NextPDF avec CodeIgniter 4

En bref

La configuration se trouve dans NextPDF\CodeIgniter\Config\NextPdf, une sous-classe CodeIgniter de BaseConfig. Tu peux surcharger les valeurs en étendant la classe dans app/Config/ ou en définissant des clés .env avec le préfixe nextpdf.. Les valeurs par défaut suffisent sans configuration supplémentaire.

Vue d’ensemble conceptuelle

NextPdf est un BaseConfig typé. La classe n’est volontairement pas déclarée final. La convention de CodeIgniter veut que la configuration de l’application étende la classe du package, afin que l’application puisse surcharger les valeurs par défaut. Quand CodeIgniter construit la configuration, BaseConfig résout les surcharges d’environnement pour chaque propriété publique. Cette résolution s’applique aussi aux clés des tableaux imbriqués.

Les chemins par défaut des polices et du cache utilisent la constante CodeIgniter WRITEPATH : WRITEPATH . 'fonts' et WRITEPATH . 'cache/nextpdf'.

Clés de configuration

Chaque clé ci-dessous est une propriété publique de NextPdf. Les valeurs par défaut proviennent des valeurs vérifiées dans le code source du package.

Valeurs par défaut de la page et du document

Clé	Type	Valeur par défaut	Description
pageFormat	string	A4	Format de page.
orientation	string	P	P portrait ou L paysage.
unit	string	mm	Unité de mesure.
defaults.creator	string	NextPDF	Métadonnée créateur du PDF.
defaults.author	string	''	Métadonnée auteur ; ignorée si vide.
defaults.language	string	en	Balise de langue du document.
defaults.margin_top	float	10.0	Marge haute.
defaults.margin_right	float	10.0	Marge droite.
defaults.margin_bottom	float	10.0	Marge basse.
defaults.margin_left	float	10.0	Marge gauche.
defaults.font_family	string	dejavusans	Police par défaut.
defaults.font_size	float	12.0	Taille de police par défaut.
defaults.trim_box	list<float>|null	null	Boîte de rognage, si définie.
defaults.bleed_box	list<float>|null	null	Boîte de fond perdu, si définie.

Le package applique defaults.creator et defaults.language à chaque document. Il applique defaults.author uniquement si cette valeur est non vide.

Chemins et caches

Clé	Type	Valeur par défaut	Description
fontsPath	string	WRITEPATH/fonts	Répertoire des fichiers de police.
cachePath	string	WRITEPATH/cache/nextpdf	Répertoire de cache.
preloadFonts	list<string>	[]	Chemins de police absolus préchargés au démarrage.
imageCacheMb	int	50	Budget du cache LRU des images en Mo.
fontCacheLocking	bool	true	Verrouille le cache de police après le préchauffage.

Le registre des polices rejette un fontsPath qui contient un wrapper de flux (://) ou un octet nul. Le rejet déclenche une erreur d’exécution. Consulte /integrations/codeigniter/security-and-operations/.

Archivage et couleur (NextPDF Pro)

Clé	Type	Valeur par défaut	Description
pdfa	string|null	null	Version PDF/A : 4, 4e, 4f.
iccProfile.rgb	string|null	null	Chemin du profil ICC RGB.
iccProfile.cmyk	string|null	null	Chemin du profil ICC CMYK.

pdfa ne prend effet que lorsque NextPDF Pro est installé et que la capacité d’archivage est disponible. Avec le cœur uniquement, la clé est ignorée.

Signature numérique (NextPDF Pro / Enterprise)

Clé	Type	Valeur par défaut	Description
signature.enabled	bool	false	Active le service de signature.
signature.certificate	string|null	null	Chemin du fichier de certificat.
signature.private_key	string|null	null	Chemin du fichier de clé privée.
signature.password	string	''	Mot de passe de la clé privée.
signature.extra_certs	list<string>	[]	Chemins de certificats de chaîne supplémentaires.
signature.level	string	B-B	Identifiant du niveau de signature.

Services::pdfSigner() renvoie null sauf si signature.enabled vaut true et que signature.certificate est non vide. Le niveau par défaut est B-B. NextPDF Pro fournit la signature B-B de référence. Les niveaux avec validation à long terme relèvent d’une capacité Enterprise distincte. Ils sont documentés dans la référence Premium, pas ici.

PAdES B-T est produit par le moteur Core. L’intégration CodeIgniter n’ajoute pas elle-même B-T, et Pro ne fournit que la base B-B. Cette documentation sera mise à jour si Pro B-T est publié.

Autorité d’horodatage

Clé	Type	Valeur par défaut	Description
tsa.url	string|null	null	URL du point de terminaison TSA.
tsa.username	string	''	Nom d’utilisateur pour l’authentification basique TSA.
tsa.password	string	''	Mot de passe pour l’authentification basique TSA.
tsa.cert	string|null	null	Chemin du certificat client.
tsa.key	string|null	null	Chemin de la clé client.
tsa.timeout	int	30	Délai d’expiration de la requête en secondes.
tsa.pinned_public_keys	list<string>	[]	Clés publiques TSA épinglées.
tsa.warn_on_key_rotation	bool	true	Émettre un avertissement lors de la rotation de clé TSA.
tsa.allow_insecure_http	bool	false	Autoriser le HTTP en clair vers la TSA.

Services::tsaClient() renvoie null lorsque tsa.url vaut null ou une chaîne vide. Lorsqu’un niveau de signature exigeant un horodatage est sélectionné, le signataire attache automatiquement le client TSA.

Cache OCSP

Clé	Type	Valeur par défaut	Description
ocspCache.enabled	bool	true	Active le cache de réponses OCSP.
ocspCache.ttl	int	86400	TTL du cache en secondes.
ocspCache.directory	string|null	null	Répertoire de cache ; valeur par défaut du moteur si null.

Renderer HTML Chrome (NextPDF Artisan)

Clé	Type	Valeur par défaut	Description
artisan.chrome_binary	string|null	null	Chemin du binaire Chrome/Chromium.
artisan.render_timeout	int	30	Délai d’expiration du rendu en secondes.
artisan.default_css	string	''	Feuille de style par défaut.
artisan.no_sandbox	bool	false	Passe --no-sandbox à Chrome.
artisan.max_html_size	int	5000000	Taille maximale du HTML en entrée, en octets.

Le renderer Chrome n’est configuré pour le document que lorsque artisan.chrome_binary est défini et que nextpdf/artisan est installé.

Surcharger avec .env

BaseConfig résout les surcharges d’environnement par propriété. La clé recherchée est le nom court de classe en minuscules, nextpdf, suivi du chemin de la propriété. Les clés des tableaux imbriqués sont adressées avec des points. Les formes avec points et avec traits de soulignement sont toutes deux acceptées.

.env

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Le préfixe est le nom court de classe en minuscules. Il reste nextpdf même si la classe s’écrit NextPdf. La forme pleinement qualifiée (NextPDF\CodeIgniter\Config\NextPdf.fontsPath) est aussi acceptée.

Surcharger en étendant la classe

Pour une configuration typée et versionnée, étends la classe du package dans app/Config/. CodeIgniter charge la classe de l’application à la place de la configuration par défaut du package. Ce fichier déclare une classe et ne produit aucun effet de bord. Il reste ainsi aligné sur l’attente PSR-1 selon laquelle un fichier doit soit déclarer des symboles, soit exécuter une logique à effets de bord, mais pas les deux (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Cas limites & pièges

• Surcharger une seule clé imbriquée avec .env ne surcharge que cette clé ; le reste du tableau garde sa valeur par défaut.
• .env : les valeurs sont des chaînes. CodeIgniter convertit true/false et les chaînes numériques. Mets entre guillemets les valeurs qui doivent rester des chaînes littérales.
• Étendre la classe avec un tableau defaults partiel remplace tout le tableau. Renseigne chaque clé, comme montré ci-dessus.

Notes de sécurité

Garde les chemins du certificat et de la clé hors du contrôle de version. Fournis-les via .env ou un gestionnaire de secrets. tsa.allow_insecure_http doit rester false en production. Consulte /integrations/codeigniter/security-and-operations/.

Conformité

• Le fichier d’extension de config de l’application déclare une seule classe et ne produit aucun effet de bord (PSR-1 §x1.x1.p3).

Contexte commercial

Le cœur de NextPDF est sous Apache-2.0. Les clés signature.* et pdfa ne prennent effet que lorsque NextPDF Pro ou Enterprise est installé. Le package CodeIgniter expose les méthodes de service correspondantes. Ces méthodes renvoient null tant que le package Premium correspondant n’est pas installé. Consulte </get-license/?intent=codeigniter-signing>.

Voir aussi

• /integrations/codeigniter/install/ — installer le package.
• /integrations/codeigniter/quickstart/ — créer un premier PDF.
• /integrations/codeigniter/production-usage/ — contrôleurs câblés par DI et jobs de file d’attente.
• /integrations/codeigniter/security-and-operations/ — durcir la configuration de signature et des chemins.