Template

W skrócie

NextPDF\Pro\Template parsuje definicję szablonu JSON do typowanego obiektu wartości i wiąże asocjacyjną tablicę danych z jego symbolami zastępczymi z formatowaniem świadomym typu. Wytwarza ustrukturyzowany wynik wiązania; sam nie renderuje PDF.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Żadna dodatkowa flaga możliwości w czasie wykonania nie bramkuje tego modułu poza licencją poziomu. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Szablon to dokument JSON opisujący konfigurację strony oraz listę rozmieszczonych symboli zastępczych. TemplateParser waliduje JSON i wytwarza niemutowalny TemplateDefinition. Walidacja jest ścisła: sprawdza rozmiar strony względem listy dozwolonych wartości (A3–A6, B4, B5, Letter, Legal, Tabloid), orientację (P lub L) oraz nazwę, typ i numeryczne współrzędne każdego symbolu zastępczego, a także odrzuca zduplikowane nazwy symboli zastępczych.

TemplateDataBinder wiąże tablicę danych (dopasowywaną bez rozróżniania wielkości liter do nazw symboli zastępczych) i formatuje każdą wartość według PlaceholderType:

• Text / Image / Barcode — wartość przepuszczana jako łańcuch.
• Date — formatowana z formatem symbolu zastępczego (domyślnie Y-m-d), akceptująca łańcuchy, znaczniki czasu Unix lub DateTimeInterface.
• Number — number_format z liczbą miejsc dziesiętnych z formatu (domyślnie 2).
• Currency — liczba sformatowana z łańcuchem formatu jako prefiksem (domyślnie $).
• Conditional — "true" lub "false" na podstawie prawdziwości (truthiness).

Wynikiem jest BindingResult niosący powiązane wartości, listę brakujących pól wymaganych oraz wszelkie ostrzeżenia formatowania. Zamiana powiązanych wartości na wyrenderowany PDF należy do wywołującego, z użyciem API dokumentu i pisarza z Core oraz opcjonalnego odniesienia backgroundPdf.

Dlaczego działa to w ten sposób

Parser jest jedyną autorytatywną bramą. Zamienia niezaufany JSON w niemutowalny, w pełni typowany TemplateDefinition, a wiązanie działa następnie jako czysta funkcja tej wartości. Każde pole, które później trafia do ujścia formatowania, jest umieszczone na liście dozwolonych i ograniczone długością w czasie parsowania. Rozmiar strony, orientacja, precyzja liczby oraz znaki sterujące — wszystkie zawodzą tutaj, a nie w trakcie renderowania. Łańcuchowe daty są dopasowywane do stałego zestawu kanonicznych formatów, więc wartość taka jak now czy +1 year nie może uzależnić wyjścia od zegara ściennego. Moduł zatrzymuje się celowo na BindingResult i pozostawia renderowanie, rozwiązywanie ścieżek oraz składanie tła wywołującemu, co utrzymuje granicę zaufania jawną.

Tło projektowe: Faktury i e-fakturowanie.

Kontrakt zachowania

• Wejście. Łańcuch JSON (TemplateParser) oraz tablica danych (TemplateDataBinder).
• Wyjście. TemplateDefinition z parsowania; BindingResult z wiązania.
• Walidacja. validate() zwraca listę czytelnych dla człowieka błędów i nigdy nie rzuca wyjątku; parse() rzuca InvalidArgumentException, gdy walidacja zawiedzie.
• Brakujące dane. Symbol zastępczy bez danych i z pustą wartością domyślną jest raportowany w missingFields; ten z niepustą wartością domyślną używa wartości domyślnej.
• Determinizm. Parsowanie i wiązanie są czystymi funkcjami swoich wejść.

Powierzchnia publicznego API

Typ	Rodzaj	Kluczowe składowe
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	nazwa, PlaceholderType $type, współrzędne, wartość domyślna, 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

Przykład kodu — Szybki start

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

• Łańcuch daty niedający się sparsować generuje ostrzeżenie, a oryginalny łańcuch jest zachowywany, zamiast rzucania wyjątku.
• Łańcuch formatu waluty jest używany jako dosłowny prefiks (na przykład "$" lub "EUR "), a nie jako identyfikator ustawień regionalnych (locale).
• backgroundPdf to odniesienie do ścieżki niesione na definicji; ten moduł nie otwiera go, nie waliduje ani nie składa (composite) — to zadanie renderera.
• Nazwy symboli zastępczych są dopasowywane bez rozróżniania wielkości liter; zduplikowane nazwy w JSON są błędem walidacji.

Wydajność

Parsowanie to jedno dekodowanie JSON plus walidacja strukturalna; wiązanie jest liniowe względem liczby symboli zastępczych. Zobacz performance_budget.

Uwagi dotyczące bezpieczeństwa

JSON jest dekodowany z JSON_THROW_ON_ERROR i walidowany względem stałych list dozwolonych wartości przed skonstruowaniem TemplateDefinition. Moduł nie wykonuje żadnych operacji wejścia/wyjścia plików ani sieci; ścieżka backgroundPdf nie jest tu dereferencjonowana, więc obsługa ścieżki i kontrola dostępu należą do renderera.

Zgodność ze standardami

Ten moduł nie ma bezpośredniej powierzchni specyfikacji PDF: parsuje szablon JSON i formatuje wartości. Słowniki rozmiaru strony i orientacji są konwencjami NextPDF, a nie normatywnymi konstruktami PDF.

Rozwiązanie awaryjne / alternatywa w Core

Nie ma w Core warstwy definicji szablonu. Do w pełni imperatywnego konstruowania dokumentu użyj bezpośrednio otwartoźródłowych API dokumentu i pisarza z Core. Zobacz /modules/core/document/.

Uwaga o granicy Enterprise

Ten moduł definiuje i wiąże szablony. Nie wykonuje orkiestracji mail-merge, harmonogramowania zadań wsadowych ani renderowania; te kwestie są poza zakresem i są obsługiwane w innym miejscu.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbook oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Template reference
• Toc
• Merge
• Core document model