Template

In het kort

NextPDF\Pro\Template parseert een JSON-templatedefinitie tot een getypeerd waarde- object en bindt een associatieve data-array aan zijn placeholders met type-bewuste formattering. Het produceert een gestructureerd bindingsresultaat; het rendert zelf geen PDF.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van deze functionaliteit niet. Geen extra runtime- capaciteitsvlag schermt deze module af buiten de niveaulicentie. Vergelijk edities en verkrijg een licentie.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

Een template is een JSON-document dat een paginaopzet en een lijst van gepositioneerde placeholders beschrijft. TemplateParser valideert de JSON en produceert een onveranderlijke TemplateDefinition. De validatie is strikt: het controleert de pagina- grootte tegen een allow-list (A3–A6, B4, B5, Letter, Legal, Tabloid), oriëntatie (P of L) en de naam, het type en de numerieke coördinaten van elke placeholder, en het wijst dubbele placeholdernamen af.

TemplateDataBinder bindt een data-array (hoofdletterongevoelig gematcht aan placeholdernamen) en formatteert elke waarde per PlaceholderType:

• Text / Image / Barcode — waarde wordt als string doorgegeven.
• Date — geformatteerd met het format van de placeholder (standaard Y-m-d), accepteert strings, Unix-timestamps of DateTimeInterface.
• Number — number_format met decimalen uit het format (standaard 2).
• Currency — getal geformatteerd met het format-string als prefix (standaard $).
• Conditional — "true" of "false" op basis van truthiness.

Het resultaat is een BindingResult die de gebonden waarden, de lijst van ontbrekende verplichte velden en eventuele formatteringswaarschuwingen draagt. Het omzetten van gebonden waarden naar een gerenderde PDF is de verantwoordelijkheid van de caller, met behulp van de Core-document- en writer-API’s en de optionele backgroundPdf-referentie.

Waarom het zo werkt

De parser is de enige gezaghebbende poort. Het zet niet-vertrouwde JSON om in een onveranderlijke, volledig getypeerde TemplateDefinition, en het binden draait vervolgens als een pure functie van die waarde. Elk veld dat later een formatteringssink bereikt, is allow-listed en lengtebegrensd op parse-tijd. Paginagrootte, oriëntatie, getal- precisie en stuurtekens falen hier, niet halverwege het renderen. String-datums worden gematcht tegen een vaste set canonieke formats, zodat een waarde als now of +1 year de uitvoer niet afhankelijk kan maken van de wandklok. De module stopt doelbewust bij een BindingResult en laat rendering, padresolutie en achtergrondcompositie over aan de caller, wat de vertrouwensgrens expliciet houdt.

Ontwerpachtergrond: Facturen en e-invoicing.

Gedragscontract

• Invoer. Een JSON-string (TemplateParser) en een data-array (TemplateDataBinder).
• Uitvoer. TemplateDefinition uit het parsen; BindingResult uit het binden.
• Validatie. validate() retourneert een lijst met leesbare fouten en werpt nooit; parse() werpt InvalidArgumentException wanneer de validatie faalt.
• Ontbrekende data. Een placeholder zonder data en met een lege default wordt gerapporteerd in missingFields; een met een niet-lege default gebruikt de default.
• Determinisme. Parsen en binden zijn pure functies van hun invoer.

Publiek API-oppervlak

Type	Soort	Belangrijkste leden
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	naam, PlaceholderType $type, coördinaten, default, 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

Codevoorbeeld — Snelstart

<?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";
}

Codevoorbeeld — Productie

<?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
}

Randgevallen en valkuilen

• Een niet-parseerbare datumstring produceert een waarschuwing en de oorspronkelijke string wordt behouden, in plaats van te werpen.
• De currency-format-string wordt gebruikt als een letterlijke prefix (bijvoorbeeld "$" of "EUR "), niet als een locale-identifier.
• backgroundPdf is een padreferentie die op de definitie wordt gedragen; deze module opent, valideert of composit het niet — dat is de taak van de renderer.
• Placeholdernamen worden hoofdletterongevoelig gematcht; dubbele namen in de JSON zijn een validatiefout.

Prestaties

Parsen is één JSON-decode plus structurele validatie; binden is lineair in het aantal placeholders. Zie performance_budget.

Beveiligingsnotities

JSON wordt gedecodeerd met JSON_THROW_ON_ERROR en gevalideerd tegen vaste allow-lists voordat een TemplateDefinition wordt geconstrueerd. De module voert geen bestand- of netwerk-I/O uit; het backgroundPdf-pad wordt hier niet gedereferentieerd, dus padverwerking en toegangscontrole behoren tot de renderer.

Conformiteit

Deze module heeft geen direct PDF-specificatieoppervlak: het parseert een JSON- template en formatteert waarden. De pagina-grootte- en oriëntatievocabulaires zijn NextPDF-conventies, geen normatieve PDF-constructies.

Core-fallback / alternatief

Er is geen Core-templatedefinitielaag. Voor volledig imperatieve documentconstructie gebruik je de open-source Core-document- en writer-API’s rechtstreeks. Zie /modules/core/document/.

Enterprise-grensnotitie

Deze module definieert en bindt templates. Het voert geen mail-merge- orchestratie, batch job-planning of rendering uit; die zaken vallen buiten de scope en worden elders afgehandeld.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixes vallen buiten de scope.

Zie ook

• Template reference
• Toc
• Merge
• Core-documentmodel