Modèle

En bref

NextPDF\Pro\Template analyse une définition de modèle JSON en un objet valeur typé et lie un tableau de données associatif à ses placeholders avec un formatage tenant compte du type. Il produit un résultat de liaison structuré ; il ne rend pas lui-même un PDF.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Aucun indicateur de capacité d’exécution supplémentaire ne restreint ce module au-delà de la licence de niveau. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Un modèle est un document JSON décrivant une configuration de page et une liste de placeholders positionnés. TemplateParser valide le JSON et produit une TemplateDefinition immuable. La validation est stricte : elle vérifie la taille de page par rapport à une liste d’autorisation (A3–A6, B4, B5, Letter, Legal, Tabloid), l’orientation (P ou L), ainsi que le nom, le type et les coordonnées numériques de chaque placeholder, et elle rejette les noms de placeholder en double.

TemplateDataBinder lie un tableau de données (apparié de façon insensible à la casse aux noms de placeholder) et formate chaque valeur selon PlaceholderType :

• Text / Image / Barcode — valeur transmise telle quelle sous forme de chaîne.
• Date — formatée avec le format du placeholder (par défaut Y-m-d), acceptant des chaînes, des timestamps Unix ou DateTimeInterface.
• Number — number_format avec les décimales issues du format (par défaut 2).
• Currency — nombre formaté avec la chaîne de format en préfixe (par défaut $).
• Conditional — "true" ou "false" selon la véracité.

Le résultat est un BindingResult portant les valeurs liées, la liste des champs requis manquants, et les éventuels avertissements de formatage. Transformer les valeurs liées en un PDF rendu est de la responsabilité de l’appelant, à l’aide des API document et writer de Core et de la référence optionnelle backgroundPdf.

Pourquoi ça fonctionne ainsi

Le parseur est l’unique point de contrôle faisant autorité. Il transforme du JSON non fiable en une TemplateDefinition immuable et entièrement typée, puis la liaison s’exécute ensuite comme une fonction pure de cette valeur. Chaque champ qui atteint plus tard un point de formatage est sur liste d’autorisation et borné en longueur au moment de l’analyse. La taille de page, l’orientation, la précision numérique et les caractères de contrôle échouent tous ici, et non en cours de rendu. Les dates sous forme de chaîne sont appariées à un ensemble fixe de formats canoniques, de sorte qu’une valeur comme now ou +1 year ne peut pas faire dépendre la sortie de l’horloge système. Le module s’arrête délibérément à un BindingResult et laisse le rendu, la résolution des chemins et la composition d’arrière-plan à l’appelant, ce qui maintient la frontière de confiance explicite.

Contexte de conception : Factures et facturation électronique.

Contrat de comportement

• Entrée. Une chaîne JSON (TemplateParser) et un tableau de données (TemplateDataBinder).
• Sortie. TemplateDefinition issue de l’analyse ; BindingResult issu de la liaison.
• Validation. validate() renvoie une liste d’erreurs lisibles par un humain et ne lève jamais ; parse() lève InvalidArgumentException lorsque la validation échoue.
• Données manquantes. Un placeholder sans donnée et avec une valeur par défaut vide est signalé dans missingFields ; un placeholder avec une valeur par défaut non vide utilise la valeur par défaut.
• Déterminisme. L’analyse et la liaison sont des fonctions pures de leurs entrées.

Surface d’API publique

Type	Genre	Membres clés
NextPDF\Pro\Template\TemplateParser	final class	parse(string $json): TemplateDefinition, validate(string $json): list<string>
NextPDF\Pro\Template\TemplateDataBinder	final class	bind(TemplateDefinition $template, array $data): BindingResult
NextPDF\Pro\Template\TemplateDefinition	final readonly class	string $name, string $pageSize, string $orientation, array $placeholders, string $backgroundPdf, getPlaceholder(string $name): ?TemplatePlaceholder, requiredFields(): list<string>
NextPDF\Pro\Template\TemplatePlaceholder	final readonly class	nom, PlaceholderType $type, coordonnées, valeur par défaut, format
NextPDF\Pro\Template\BindingResult	final readonly class	array $bindings, array $missingFields, array $warnings
NextPDF\Pro\Template\PlaceholderType	enum	Text, Image, Barcode, Date, Number, Currency, Conditional; requiresFormatting(): bool

Exemple de code — Démarrage rapide

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

$json = '{"name":"Invoice","pageSize":"A4","orientation":"P","placeholders":'
 . '[{"name":"total","type":"currency","x":400,"y":700,"width":120,'
 . '"height":18,"format":"$"}]}';

$template = (new TemplateParser())->parse($json);
$result = (new TemplateDataBinder())->bind($template, ['total' => 1299.5]);

foreach ($result->bindings as $bound) {
 echo $bound->placeholder->name, ' => ', $bound->formattedValue, "\n";
}

Exemple de code — Production

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

function bindOrReject(string $json, array $data): array
{
 $parser = new TemplateParser();

 $errors = $parser->validate($json);
 if ($errors !== []) {
 throw new InvalidArgumentException(implode('; ', $errors));
 }

 $template = $parser->parse($json);
 $result = (new TemplateDataBinder())->bind($template, $data);

 if ($result->missingFields !== []) {
 throw new RuntimeException(
 'missing required fields: ' . implode(', ', $result->missingFields),
 );
 }

 return $result->bindings; // hand to the renderer
}

Cas limites et pièges

• Une chaîne de date non analysable produit un avertissement et la chaîne d’origine est conservée, plutôt que de lever une exception.
• La chaîne de format de devise est utilisée comme préfixe littéral (par exemple "$" ou "EUR "), et non comme un identifiant de locale.
• backgroundPdf est une référence de chemin portée sur la définition ; ce module ne l’ouvre pas, ne le valide pas et ne le compose pas — c’est le travail du moteur de rendu.
• Les noms de placeholder sont appariés de façon insensible à la casse ; des noms en double dans le JSON constituent une erreur de validation.

Performance

L’analyse est un seul décodage JSON plus une validation structurelle ; la liaison est linéaire en nombre de placeholders. Voir performance_budget.

Notes de sécurité

Le JSON est décodé avec JSON_THROW_ON_ERROR et validé par rapport à des listes d’autorisation fixes avant qu’une TemplateDefinition ne soit construite. Le module n’effectue aucune E/S de fichier ou réseau ; le chemin backgroundPdf n’est pas déréférencé ici, si bien que la manipulation des chemins et le contrôle d’accès reviennent au moteur de rendu.

Conformité

Ce module n’a aucune surface de spécification PDF directe : il analyse un modèle JSON et formate des valeurs. Les vocabulaires de taille de page et d’orientation sont des conventions NextPDF, et non des constructions PDF normatives.

Repli / alternative Core

Il n’existe pas de couche de définition de modèle dans Core. Pour une construction de document entièrement impérative, utilise directement les API document et writer de Core open source. Voir /modules/core/document/.

Note sur la frontière Enterprise

Ce module définit et lie des modèles. Il n’effectue pas d’orchestration de publipostage, de planification de jobs par lot, ni de rendu ; ces préoccupations sont hors de portée et sont gérées ailleurs.

Frontière 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 tickets sont hors de portée.

Voir aussi

• Référence Template
• Toc
• Merge
• Modèle de document Core