Template — Référence détaillée

En bref

Cette référence détaillée documente le schéma JSON de template accepté, chaque règle de validation et le comportement exact de formatage par type du binder de données. Le module analyse une définition de template, puis lie les données de l’appelant à des placeholders typés. Il produit des chaînes formatées ; il ne dessine pas d’objets PDF.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement sans cette autorisation ne charge pas les classes de la capacité. Aucun indicateur de capacité à l’exécution ne conditionne ce module. Comparer les éditions et obtenir une licence.

Surface d’API publique

Le module expose deux services de point d’entrée et quatre objets valeur immuables. Chaque symbole ci-dessous est public et stable.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
TemplateParser::parse	string $json	Valide, puis construit la définition	TemplateDefinition	InvalidArgumentException lorsqu’une erreur de validation est présente	Délègue d’abord à validate.
TemplateParser::validate	string $json	Collecte toutes les erreurs structurelles en une seule passe	list<string> (vide si valide)	Ne lève jamais ; un échec de décodage JSON est retourné sous forme de message	Contrôle de référence pour les bornes de longueur et de précision.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Associe les placeholders sans tenir compte de la casse et formate par type	BindingResult	Ne lève jamais ; les anomalies deviennent des avertissements ou des champs manquants	Utilise la valeur par défaut d’un placeholder lorsque la clé est absente.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Stocke la définition analysée	TemplateDefinition	TypeError en cas d’incompatibilité de type d’argument	Objet valeur final readonly.
TemplateDefinition::getPlaceholder	string $name	Recherche par nom sans tenir compte de la casse	TemplatePlaceholder|null	Aucune défaillance ; retourne null si absent	—
TemplateDefinition::requiredFields	aucun	Collecte les noms des placeholders sans valeur par défaut	list<string>	Aucune défaillance	Une valeur par défaut non vide rend un placeholder optionnel.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Stocke une région de placeholder	TemplatePlaceholder	TypeError en cas d’incompatibilité de type d’argument	Les coordonnées sont des points depuis le coin supérieur gauche.
TemplatePlaceholder::matches	string $key	Comparaison de nom sans tenir compte de la casse	bool	Aucune défaillance	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Stocke le résultat de la liaison	BindingResult	TypeError en cas d’incompatibilité de type d’argument	Objet valeur final readonly.
BindingResult::isComplete	aucun	Indique si tous les champs requis ont été liés	bool	Aucune défaillance	Vrai lorsque missingFields est vide.
BindingResult::count	aucun	Compte les placeholders liés avec succès	int	Aucune défaillance	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Associe un placeholder à sa valeur formatée	BoundPlaceholder	TypeError en cas d’incompatibilité de type d’argument	Objet valeur final readonly.
PlaceholderType	cas d’enum Text, Image, Barcode, Date, Number, Currency, Conditional	Taxonomie de placeholders adossée à des chaînes	instance d’enum	ValueError depuis from() sur une valeur inconnue	tryFrom() retourne null à la place.
PlaceholderType::requiresFormatting	aucun	Indique si le type consomme une chaîne de format	bool	Aucune défaillance	Vrai pour Date, Number, Currency.

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

Contrat de comportement

Forme JSON acceptée :

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

Règles de validation, toutes remontées par validate sous forme de messages et agrégées par parse en une seule exception :

• name manquant ou vide.
• pageSize hors de la liste autorisée, ou orientation différent de P ou L.
• placeholders manquant, ou valeur non tableau.
• Par placeholder : nom manquant ou vide ; type invalide ; x, y, width, height manquants ou non numériques ; nom en double (sans tenir compte de la casse).
• defaultValue : non chaîne, de plus de 4096 octets, ou porteur d’un caractère de contrôle ASCII.
• format : non chaîne, de plus de 256 octets, ou porteur d’un caractère de contrôle ASCII.
• Un format de placeholder number qui n’est pas un entier positif ou nul, ou qui dépasse 30.

Sémantique de liaison (TemplateDataBinder::bind) :

• Les clés de données sont mises en minuscules pour une correspondance sans tenir compte de la casse avec les noms de placeholders.
• Une clé absente avec une valeur par défaut non vide lie la valeur par défaut ; une clé absente qui n’en a pas est signalée dans missingFields.
• Les valeurs text, image et barcode sont converties en chaîne sans modification.
• La liaison date accepte un DateTimeInterface, un timestamp Unix entier, ou une chaîne dans l’un des quatre formats explicites. Le format de sortie par défaut est Y-m-d.
• La liaison number utilise number_format(value, decimals, '.', ','). Le nombre de décimales provient de format, vaut 2 par défaut, et est borné à la plage 0 à 30.
• La liaison currency préfixe le nombre formaté avec format, le préfixe valant $ par défaut.
• La liaison conditional émet "true" ou "false" à partir d’une conversion booléenne.

Cas limites et modes de défaillance

• backgroundPdf n’est jamais ouvert ni déréférencé par ce module. C’est une chaîne opaque transmise au moteur de rendu.
• Une valeur non numérique liée à un placeholder Number ou Currency produit un avertissement ; la valeur est convertie en chaîne, pas rejetée.
• Les chaînes de date sont analysées strictement. Les jetons relatifs et en langage naturel (« now », « +1 year », « tomorrow ») ne correspondent à aucun format accepté, ils déclenchent donc un avertissement et la valeur brute est transmise sans modification.
• Une valeur de date entière est lue comme un timestamp Unix via la forme d’époque @.
• Une précision de format Number hors de la plage 0 à 30 qui atteint le binder est rejetée avec un avertissement ; le binder revient à la précision par défaut de 2.
• Aucune opération cryptographique n’a lieu dans ce module, il n’y a donc aucun comportement spécifique au mode FIPS.

Conformité

Aucune surface de spécification PDF directe n’existe. Les vocabulaires de taille de page et d’orientation sont des conventions NextPDF, et le module émet des valeurs formatées, pas des objets PDF. La liste autorisée stricte de dates sous forme de chaîne accepte le profil Internet date/heure d’ISO 8601 défini dans la RFC 3339 §5.6, aux côtés d’une date calendaire Y-m-d et de deux formes date-heure locales. NextPDF documente la capacité à lire ces formats ; il ne revendique aucune certification vis-à-vis de la RFC 3339 ou d’ISO 8601.

Notes de développement

• TemplateParser et TemplateDataBinder sont sans état. Une seule instance est réutilisable et peut être partagée sans risque entre les liaisons.
• Les quatre objets valeur sont final readonly ; construis-les via le parser plutôt qu’à la main pour des données de production.
• validate signale chaque erreur structurelle en une seule passe, tandis que parse appelle d’abord validate et lève sur le message agrégé. Utilise validate pour un retour de type formulaire et parse pour une ingestion fail-fast.
• Les bornes de longueur et de précision sont appliquées au niveau du parser en tant que contrôle de référence. TemplateDataBinder revérifie la précision numérique comme garde côté sortie contre l’amplification mémoire de number_format.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

• Template (guide de capacité)
• Toc
• Merge