Template — Diepe referentie

In het kort

Deze diepe referentie documenteert het geaccepteerde JSON-templateschema, elke validatieregel en het exacte formatteringsgedrag per type van de data binder. De module parseert een templatedefinitie en bindt vervolgens caller-data aan getypeerde placeholders. Ze zendt geformatteerde strings uit; ze tekent geen PDF-objecten.

Beschikbaarheid en licentiëring

Deze capability wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een license-envelope van het Pro-niveau. Een deployment zonder dat recht laadt de klassen van de capability niet. Geen runtime-capability-flag schermt deze module af. Vergelijk edities en verkrijg een licentie.

Publiek API-oppervlak

De module stelt twee entry-point-services en vier immutable value objects beschikbaar. Elk symbool hieronder is public en stabiel.

Symbool	Parameters	Standaardgedrag	Geeft terug	Werpt of faalt met	Opmerkingen
TemplateParser::parse	string $json	Valideert en bouwt daarna de definitie	TemplateDefinition	InvalidArgumentException wanneer er een validatiefout aanwezig is	Delegeert eerst naar validate.
TemplateParser::validate	string $json	Verzamelt alle structurele fouten in één keer	list<string> (leeg wanneer geldig)	Werpt nooit; een JSON-decodeerfout wordt als melding teruggegeven	Gezaghebbende poort voor lengte- en precisiegrenzen.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Matcht placeholders hoofdletterongevoelig en formatteert per type	BindingResult	Werpt nooit; afwijkingen worden waarschuwingen of ontbrekende velden	Gebruikt de standaardwaarde van een placeholder wanneer de sleutel ontbreekt.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Slaat de geparseerde definitie op	TemplateDefinition	TypeError bij een type-mismatch van een argument	Final readonly value object.
TemplateDefinition::getPlaceholder	string $name	Hoofdletterongevoelige opzoeking op naam	TemplatePlaceholder|null	Geen fout; geeft null terug wanneer afwezig	—
TemplateDefinition::requiredFields	geen	Verzamelt namen van placeholders zonder standaardwaarde	list<string>	Geen fout	Een niet-lege standaardwaarde maakt een placeholder optioneel.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Slaat één placeholder-regio op	TemplatePlaceholder	TypeError bij een type-mismatch van een argument	Coördinaten zijn punten vanaf linksboven.
TemplatePlaceholder::matches	string $key	Hoofdletterongevoelige naamvergelijking	bool	Geen fout	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Slaat de bindingsuitkomst op	BindingResult	TypeError bij een type-mismatch van een argument	Final readonly value object.
BindingResult::isComplete	geen	Rapporteert of elk vereist veld is gebonden	bool	Geen fout	True wanneer missingFields leeg is.
BindingResult::count	geen	Telt succesvol gebonden placeholders	int	Geen fout	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Koppelt een placeholder aan zijn geformatteerde waarde	BoundPlaceholder	TypeError bij een type-mismatch van een argument	Final readonly value object.
PlaceholderType	enum-cases Text, Image, Barcode, Date, Number, Currency, Conditional	String-backed placeholder-taxonomie	enum-instantie	ValueError van from() bij een onbekende waarde	tryFrom() geeft in plaats daarvan null terug.
PlaceholderType::requiresFormatting	geen	Rapporteert of het type een format-string gebruikt	bool	Geen fout	True voor 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;
}

Gedragscontract

Geaccepteerde JSON-vorm:

{
  "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" }
  ]
}

Validatieregels, alle door validate als meldingen naar boven gebracht en door parse geaggregeerd tot één exception:

• Ontbrekende of lege name.
• pageSize buiten de allow-list, of orientation niet P of L.
• Ontbrekende placeholders, of een niet-array-waarde.
• Per placeholder: ontbrekende of lege naam; ongeldig type; ontbrekende of niet-numerieke x, y, width, height; dubbele naam (hoofdletterongevoelig).
• defaultValue: geen string, langer dan 4096 bytes, of met een ASCII-controlekarakter.
• format: geen string, langer dan 256 bytes, of met een ASCII-controlekarakter.
• Een format van een number-placeholder die geen niet-negatief geheel getal is, of die 30 overschrijdt.

Bindingssemantiek (TemplateDataBinder::bind):

• Datasleutels worden naar kleine letters omgezet voor hoofdletterongevoelige matching tegen placeholdernamen.
• Een ontbrekende sleutel met een niet-lege standaardwaarde bindt de standaardwaarde; een ontbrekende sleutel zonder standaardwaarde wordt gerapporteerd in missingFields.
• Text-, image- en barcode-waarden worden ongewijzigd naar string gecast.
• Datumbinding accepteert een DateTimeInterface, een integer Unix-timestamp of een string in een van vier expliciete formaten. Het standaard-uitvoerformaat is Y-m-d.
• Getalbinding gebruikt number_format(value, decimals, '.', ','). Het aantal decimalen komt uit format, is standaard 2 en wordt begrensd tot het bereik 0 tot en met 30.
• Currency-binding laat format voorafgaan aan het geformatteerde getal, met $ als standaardprefix.
• Conditional-binding zendt "true" of "false" uit vanuit een boolean-cast.

Randgevallen en foutmodi

• backgroundPdf wordt door deze module nooit geopend of gedereferentieerd. Het is een ondoorzichtige string die aan de renderer wordt doorgegeven.
• Een niet-numerieke waarde die aan een Number- of Currency-placeholder wordt gebonden, produceert een waarschuwing; de waarde wordt naar string gecast, niet afgewezen.
• Datumstrings worden strikt geparseerd. Relatieve en natuurlijketaal-tokens (“now”, “+1 year”, “tomorrow”) matchen geen enkel geaccepteerd formaat, dus ze geven een waarschuwing en de ruwe waarde passeert ongewijzigd.
• Een integer-datumwaarde wordt gelezen als een Unix-timestamp via de @-epochvorm.
• Een Number-format-precisie buiten 0 tot en met 30 die de binder bereikt, wordt met een waarschuwing afgewezen; de binder valt terug op de standaardprecisie van 2.
• Er vindt geen cryptografische bewerking plaats in deze module, dus er is geen FIPS-modus specifiek gedrag.

Conformiteit

Er bestaat geen direct PDF-specificatieoppervlak. Pagina-grootte- en oriëntatie vocabulaires zijn NextPDF-conventies, en de module zendt geformatteerde waarden uit, geen PDF-objecten. De strikte allow-list voor string-datums accepteert het Internet date/time-profiel van ISO 8601 gedefinieerd in RFC 3339 §5.6, naast een Y-m-d-kalenderdatum en twee lokale datum-tijd-vormen. NextPDF documenteert de mogelijkheid om deze formaten te lezen; het claimt geen certificering tegen RFC 3339 of ISO 8601.

Ontwikkelnotities

• TemplateParser en TemplateDataBinder zijn stateless. Eén instantie is herbruikbaar en veilig om te delen over bindingen heen.
• De vier value objects zijn final readonly; construeer ze via de parser in plaats van met de hand voor productie-input.
• validate rapporteert elke structurele fout in één keer, terwijl parse eerst validate aanroept en werpt op de geaggregeerde melding. Gebruik validate voor formulierachtige feedback en parse voor fail-fast ingestie.
• De lengte- en precisiegrenzen worden bij de parser afgedwongen als gezaghebbende poort. TemplateDataBinder controleert de getalprecisie opnieuw als sink-side-bescherming tegen geheugenamplificatie door number_format.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde public API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Template (capability-gids)
• Toc
• Merge