Template

Auf einen Blick

NextPDF\Pro\Template parst eine JSON-Template-Definition in ein typisiertes Value Object und bindet ein assoziatives Datenarray mit typabhängiger Formatierung an dessen Platzhalter. Es erzeugt ein strukturiertes Bindungsergebnis; es rendert nicht selbst ein PDF.

Verfügbarkeit & Lizenzierung

Diese Funktion wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einer Lizenzhülle der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Kein zusätzliches Laufzeit- Capability-Flag gatet dieses Modul über die Stufenlizenz hinaus. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Ein Template ist ein JSON-Dokument, das ein Seiten-Setup und eine Liste positionierter Platzhalter beschreibt. TemplateParser validiert das JSON und erzeugt eine immutable TemplateDefinition. Die Validierung ist strikt: Sie prüft die Seitengröße gegen eine Allow-List (A3–A6, B4, B5, Letter, Legal, Tabloid), die Orientierung (P oder L) sowie den Namen, Typ und die numerischen Koordinaten jedes Platzhalters und weist doppelte Platzhalternamen zurück.

TemplateDataBinder bindet ein Datenarray (case-insensitiv an die Platzhalternamen gematcht) und formatiert jeden Wert nach PlaceholderType:

• Text / Image / Barcode — Wert als String durchgereicht.
• Date — formatiert mit dem Format des Platzhalters (Standard Y-m-d), akzeptiert Strings, Unix-Zeitstempel oder DateTimeInterface.
• Number — number_format mit Dezimalstellen aus dem Format (Standard 2).
• Currency — Zahl formatiert mit dem Format-String als Präfix (Standard $).
• Conditional — "true" oder "false" basierend auf der Wahrheitswertigkeit.

Das Ergebnis ist ein BindingResult, das die gebundenen Werte, die Liste der fehlenden Pflichtfelder und etwaige Formatierungswarnungen trägt. Das Umwandeln gebundener Werte in ein gerendertes PDF liegt in der Verantwortung des Aufrufers, unter Nutzung der Core-Dokument- und Writer-APIs und der optionalen backgroundPdf-Referenz.

Warum es so funktioniert

Der Parser ist das einzige maßgebliche Gate. Er wandelt nicht vertrauenswürdiges JSON in eine immutable, vollständig typisierte TemplateDefinition, und das Binden läuft dann als reine Funktion dieses Werts. Jedes Feld, das später eine Formatierungssenke erreicht, wird zur Parse-Zeit per Allow-List geführt und längenbegrenzt. Seitengröße, Orientierung, Zahlen- präzision und Steuerzeichen scheitern hier, nicht mitten im Rendern. String-Daten werden gegen einen festen Satz kanonischer Formate gematcht, sodass ein Wert wie now oder +1 year die Ausgabe nicht von der Wanduhr abhängig machen kann. Das Modul stoppt bewusst bei einem BindingResult und überlässt Rendering, Pfadauflösung und Hintergrund-Compositing dem Aufrufer, was die Vertrauensgrenze explizit hält.

Design-Hintergrund: Rechnungen und E-Invoicing.

Verhaltensvertrag

• Eingabe. Ein JSON-String (TemplateParser) und ein Datenarray (TemplateDataBinder).
• Ausgabe. TemplateDefinition aus dem Parsen; BindingResult aus dem Binden.
• Validierung. validate() gibt eine Liste menschenlesbarer Fehler zurück und wirft niemals; parse() wirft InvalidArgumentException, wenn die Validierung fehlschlägt.
• Fehlende Daten. Ein Platzhalter ohne Daten und mit leerem Default wird in missingFields gemeldet; einer mit einem nicht-leeren Default verwendet den Default.
• Determinismus. Parsen und Binden sind reine Funktionen ihrer Eingaben.

Öffentliche API-Oberfläche

Typ	Art	Wichtige Mitglieder
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	Name, PlaceholderType $type, Koordinaten, 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

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Sonderfälle & Fallstricke

• Ein nicht parsbarer Datums-String erzeugt eine Warnung, und der ursprüngliche String wird beibehalten, statt zu werfen.
• Der Currency-Format-String wird als literales Präfix verwendet (zum Beispiel "$" oder "EUR "), nicht als Locale-Identifier.
• backgroundPdf ist eine Pfadreferenz, die auf der Definition getragen wird; dieses Modul öffnet, validiert oder kompositiert sie nicht — das ist die Aufgabe des Renderers.
• Platzhalternamen werden case-insensitiv gematcht; doppelte Namen im JSON sind ein Validierungsfehler.

Performance

Das Parsen ist ein JSON-Decode plus strukturelle Validierung; das Binden ist linear in der Platzhalteranzahl. Siehe performance_budget.

Sicherheitshinweise

JSON wird mit JSON_THROW_ON_ERROR dekodiert und gegen feste Allow-Lists validiert, bevor eine TemplateDefinition konstruiert wird. Das Modul führt keine Datei- oder Netzwerk-I/O durch; der backgroundPdf-Pfad wird hier nicht dereferenziert, sodass die Pfadbehandlung und die Zugriffskontrolle dem Renderer obliegen.

Konformität

Dieses Modul hat keine direkte PDF-Spezifikationsoberfläche: Es parst ein JSON- Template und formatiert Werte. Die Vokabulare für Seitengröße und Orientierung sind NextPDF-Konventionen, keine normativen PDF-Konstrukte.

Core-Fallback / Alternative

Es gibt keine Core-Template-Definitionsschicht. Für eine vollständig imperative Dokument- konstruktion nutzen Sie die Open-Source-Core-Dokument- und Writer-APIs direkt. Siehe /modules/core/document/.

Hinweis zur Enterprise-Grenze

Dieses Modul definiert und bindet Templates. Es führt keine Mail-Merge- Orchestrierung, keine Batch-Job-Planung und kein Rendering durch; diese Anliegen liegen außerhalb des Umfangs und werden anderswo behandelt.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Template-Referenz
• Toc
• Merge
• Core document model