Pro Edition

Template — Ausführliche Referenz

Auf einen Blick

Diese Tiefenreferenz dokumentiert das akzeptierte JSON-Template-Schema, jede Validierungsregel und das exakte typspezifische Formatierungsverhalten des Datenbinders. Das Modul parst eine Template-Definition und bindet anschließend die Aufruferdaten an typisierte Platzhalter. Es gibt formatierte Zeichenketten aus; es zeichnet keine PDF-Objekte.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und wird mit einem Lizenzumschlag der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Kein Runtime-Capability-Flag steuert dieses Modul. Editionen vergleichen und eine Lizenz erwerben.

Öffentliche API-Oberfläche

Das Modul stellt zwei Einstiegspunkt-Services und vier unveränderliche Value Objects bereit. Jedes Symbol unten ist öffentlich und stabil.

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder scheitert mit	Hinweise
`TemplateParser::parse`	`string $json`	Validiert, dann baut die Definition	`TemplateDefinition`	`InvalidArgumentException`, wenn ein Validierungsfehler vorliegt	Delegiert zunächst an `validate`.
`TemplateParser::validate`	`string $json`	Sammelt alle strukturellen Fehler in einem Durchlauf	`list<string>` (leer, wenn gültig)	Löst nie aus; ein JSON-Dekodierungsfehler wird als Meldung zurückgegeben	Maßgebliche Kontrolle für Längen- und Präzisionsgrenzen.
`TemplateDataBinder::bind`	`TemplateDefinition $template`, `array<string,mixed> $data`	Gleicht Platzhalter ohne Berücksichtigung der Groß-/Kleinschreibung ab und formatiert nach Typ	`BindingResult`	Löst nie aus; Anomalien werden zu Warnungen oder fehlenden Feldern	Verwendet den Standardwert eines Platzhalters, wenn der Schlüssel fehlt.
`TemplateDefinition::__construct`	`string $name`, `string $pageSize`, `string $orientation`, `list<TemplatePlaceholder> $placeholders`, `string $backgroundPdf = ''`	Speichert die geparste Definition	`TemplateDefinition`	`TypeError` bei einem Argumenttyp-Konflikt	Finales readonly Value Object.
`TemplateDefinition::getPlaceholder`	`string $name`	Suche nach Name ohne Berücksichtigung der Groß-/Kleinschreibung	`TemplatePlaceholder\|null`	Kein Fehler; gibt `null` zurück, wenn nicht vorhanden	—
`TemplateDefinition::requiredFields`	keine	Sammelt Namen von Platzhaltern, die keinen Standardwert haben	`list<string>`	Kein Fehler	Ein nicht-leerer Standardwert markiert einen Platzhalter als optional.
`TemplatePlaceholder::__construct`	`string $name`, `PlaceholderType $type`, `float $x`, `float $y`, `float $width`, `float $height`, `string $defaultValue = ''`, `string $format = ''`	Speichert eine Platzhalterregion	`TemplatePlaceholder`	`TypeError` bei einem Argumenttyp-Konflikt	Koordinaten sind Punkte von der oberen linken Ecke.
`TemplatePlaceholder::matches`	`string $key`	Namensvergleich ohne Berücksichtigung der Groß-/Kleinschreibung	`bool`	Kein Fehler	—
`BindingResult::__construct`	`list<BoundPlaceholder> $bindings`, `list<string> $missingFields`, `list<string> $warnings`	Speichert das Bindungsergebnis	`BindingResult`	`TypeError` bei einem Argumenttyp-Konflikt	Finales readonly Value Object.
`BindingResult::isComplete`	keine	Meldet, ob jedes Pflichtfeld gebunden wurde	`bool`	Kein Fehler	Wahr, wenn `missingFields` leer ist.
`BindingResult::count`	keine	Zählt erfolgreich gebundene Platzhalter	`int`	Kein Fehler	—
`BoundPlaceholder::__construct`	`TemplatePlaceholder $placeholder`, `string $formattedValue`, `mixed $rawValue`	Verknüpft einen Platzhalter mit seinem formatierten Wert	`BoundPlaceholder`	`TypeError` bei einem Argumenttyp-Konflikt	Finales readonly Value Object.
`PlaceholderType`	enum-Cases `Text`, `Image`, `Barcode`, `Date`, `Number`, `Currency`, `Conditional`	String-basierte Platzhalter-Taxonomie	enum-Instanz	`ValueError` von `from()` bei einem unbekannten Wert	`tryFrom()` gibt stattdessen `null` zurück.
`PlaceholderType::requiresFormatting`	keine	Meldet, ob der Typ eine Formatzeichenkette verbraucht	`bool`	Kein Fehler	Wahr für `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;
}

Verhaltensvertrag

Akzeptierte JSON-Struktur:

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

Validierungsregeln, alle von validate als Meldungen offengelegt und von parse zu einer einzelnen Exception zusammengefasst:

Fehlender oder leerer name.
pageSize außerhalb der Allow-List oder orientation weder P noch L.
Fehlende placeholders oder ein Wert, der kein Array ist.
Pro Platzhalter: fehlender oder leerer Name; ungültiger Typ; fehlende oder nicht-numerische x, y, width, height; doppelter Name (ohne Berücksichtigung der Groß-/Kleinschreibung).
defaultValue: kein String, länger als 4096 Bytes oder mit einem ASCII-Steuerzeichen.
format: kein String, länger als 256 Bytes oder mit einem ASCII-Steuerzeichen.
Ein format eines number-Platzhalters, das keine nicht-negative Ganzzahl ist oder 30 überschreitet.

Bindungssemantik (TemplateDataBinder::bind):

Datenschlüssel werden in Kleinbuchstaben umgewandelt, um einen Abgleich mit Platzhalternamen ohne Berücksichtigung der Groß-/Kleinschreibung zu ermöglichen.
Ein fehlender Schlüssel mit einem nicht-leeren Standardwert bindet den Standardwert; ein fehlender Schlüssel ohne einen solchen wird in missingFields gemeldet.
Text-, Image- und Barcode-Werte werden unverändert in einen String umgewandelt.
Die Datumsbindung akzeptiert ein DateTimeInterface, einen ganzzahligen Unix-Timestamp oder eine Zeichenkette in einem von vier expliziten Formaten. Das Standardausgabeformat ist Y-m-d.
Die Zahlenbindung verwendet number_format(value, decimals, '.', ','). Die Anzahl der Dezimalstellen stammt aus format, ist standardmäßig 2 und wird auf den Bereich 0 bis 30 begrenzt.
Die Währungsbindung stellt der formatierten Zahl format voran, wobei das Präfix standardmäßig $ ist.
Die bedingte Bindung gibt "true" oder "false" aus einer booleschen Umwandlung aus.

Grenzfälle & Fehlermodi

backgroundPdf wird von diesem Modul nie geöffnet oder dereferenziert. Es ist eine opake Zeichenkette, die an den Renderer übergeben wird.
Ein nicht-numerischer Wert, der an einen Number- oder Currency-Platzhalter gebunden wird, erzeugt eine Warnung; der Wert wird in einen String umgewandelt, nicht abgelehnt.
Datumszeichenketten werden strikt geparst. Relative und natürlichsprachliche Token (“now”, “+1 year”, “tomorrow”) entsprechen keinem akzeptierten Format, daher warnen sie und der Rohwert wird unverändert durchgereicht.
Ein ganzzahliger Datumswert wird über die @-Epochenform als Unix-Timestamp gelesen.
Eine Number-format-Präzision außerhalb von 0 bis 30, die den Binder erreicht, wird mit einer Warnung abgelehnt; der Binder greift auf die Standardpräzision von 2 zurück.
In diesem Modul findet keine kryptografische Operation statt, daher gibt es kein FIPS-Modus-spezifisches Verhalten.

Konformität

Es existiert keine direkte PDF-Spezifikationsoberfläche. Seitengrößen- und Ausrichtungsvokabulare sind NextPDF-Konventionen, und das Modul gibt formatierte Werte aus, keine PDF-Objekte. Die strikte String-Datums-Allow-List akzeptiert das in RFC 3339 §5.6 definierte Internet-Datum/Zeit-Profil von ISO 8601, neben einem Y-m-d-Kalenderdatum und zwei lokalen Datum/Zeit-Formen. NextPDF dokumentiert die Fähigkeit, diese Formate zu lesen; es beansprucht keine Zertifizierung gegen RFC 3339 oder ISO 8601.

Entwicklungshinweise

TemplateParser und TemplateDataBinder sind zustandslos. Eine einzelne Instanz ist wiederverwendbar und kann sicher über Bindungen hinweg geteilt werden.
Die vier Value Objects sind final readonly; erstellen Sie sie für Produktionseingaben über den Parser statt von Hand.
validate meldet jeden strukturellen Fehler in einem Durchlauf, während parse zunächst validate aufruft und bei der zusammengefassten Meldung auslöst. Verwenden Sie validate für Formular-Feedback und parse für die Fail-Fast-Aufnahme.
Die Längen- und Präzisionsgrenzen werden im Parser als maßgebliche Kontrolle durchgesetzt. TemplateDataBinder prüft die Zahlenpräzision erneut als senkenseitige Absicherung gegen number_format-Speicherverstärkung.

Veröffentlichungsgrenze

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 Geltungsbereichs.