Template — szczegółowa dokumentacja referencyjna

W skrócie

Ta szczegółowa dokumentacja referencyjna opisuje akceptowany schemat JSON szablonu, każdą regułę walidacji oraz dokładne zachowanie formatowania według typu w binderze danych. Moduł parsuje definicję szablonu, a następnie wiąże dane wywołującego z typowanymi symbolami zastępczymi. Emituje sformatowane łańcuchy; nie rysuje obiektów PDF.

Dostępność i licencjonowanie

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

Powierzchnia publicznego API

Moduł udostępnia dwie usługi wejściowe oraz cztery niezmienne obiekty wartości. Każdy symbol poniżej jest publiczny i stabilny.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
TemplateParser::parse	string $json	Waliduje, a następnie buduje definicję	TemplateDefinition	InvalidArgumentException, gdy występuje jakikolwiek błąd walidacji	Najpierw deleguje do validate.
TemplateParser::validate	string $json	Zbiera wszystkie błędy strukturalne w jednym przebiegu	list<string> (pusta, gdy poprawne)	Nigdy nie zgłasza wyjątku; niepowodzenie dekodowania JSON jest zwracane jako komunikat	Autorytatywna kontrola granic długości i precyzji.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Dopasowuje symbole zastępcze bez rozróżniania wielkości liter i formatuje według typu	BindingResult	Nigdy nie zgłasza wyjątku; anomalie stają się ostrzeżeniami lub brakującymi polami	Używa wartości domyślnej symbolu zastępczego, gdy klucza brak.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Przechowuje sparsowaną definicję	TemplateDefinition	TypeError przy niezgodności typu argumentu	Finalny obiekt wartości readonly.
TemplateDefinition::getPlaceholder	string $name	Wyszukiwanie po nazwie bez rozróżniania wielkości liter	TemplatePlaceholder|null	Bez błędu; zwraca null, gdy brak	—
TemplateDefinition::requiredFields	brak	Zbiera nazwy symboli zastępczych bez wartości domyślnej	list<string>	Bez błędu	Niepusta wartość domyślna oznacza symbol zastępczy jako opcjonalny.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Przechowuje jeden obszar symbolu zastępczego	TemplatePlaceholder	TypeError przy niezgodności typu argumentu	Współrzędne to punkty liczone od lewego górnego rogu.
TemplatePlaceholder::matches	string $key	Porównanie nazwy bez rozróżniania wielkości liter	bool	Bez błędu	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Przechowuje wynik wiązania	BindingResult	TypeError przy niezgodności typu argumentu	Finalny obiekt wartości readonly.
BindingResult::isComplete	brak	Zgłasza, czy każde wymagane pole zostało powiązane	bool	Bez błędu	Prawda, gdy missingFields jest pusta.
BindingResult::count	brak	Zlicza pomyślnie powiązane symbole zastępcze	int	Bez błędu	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Łączy symbol zastępczy z jego sformatowaną wartością	BoundPlaceholder	TypeError przy niezgodności typu argumentu	Finalny obiekt wartości readonly.
PlaceholderType	przypadki enum Text, Image, Barcode, Date, Number, Currency, Conditional	Taksonomia symboli zastępczych oparta na łańcuchach	instancja enum	ValueError z from() przy nieznanej wartości	tryFrom() zwraca zamiast tego null.
PlaceholderType::requiresFormatting	brak	Zgłasza, czy typ zużywa łańcuch formatu	bool	Bez błędu	Prawda dla 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;
}

Kontrakt zachowania

Akceptowany kształt JSON:

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

Reguły walidacji, wszystkie zgłaszane przez validate jako komunikaty i agregowane przez parse w jeden wyjątek:

• Brakujące lub puste name.
• pageSize spoza listy dozwolonych wartości lub orientation inne niż P lub L.
• Brakujące placeholders lub wartość niebędąca tablicą.
• Dla każdego symbolu zastępczego: brakująca lub pusta nazwa; nieprawidłowy typ; brakujące lub nienumeryczne x, y, width, height; zduplikowana nazwa (bez rozróżniania wielkości liter).
• defaultValue: niebędące łańcuchem, dłuższe niż 4096 bajtów lub zawierające znak sterujący ASCII.
• format: niebędące łańcuchem, dłuższe niż 256 bajtów lub zawierające znak sterujący ASCII.
• format symbolu zastępczego number, które nie jest nieujemną liczbą całkowitą lub które przekracza 30.

Semantyka wiązania (TemplateDataBinder::bind):

• Klucze danych są zamieniane na małe litery na potrzeby dopasowania bez rozróżniania wielkości liter do nazw symboli zastępczych.
• Nieobecny klucz z niepustą wartością domyślną wiąże wartość domyślną; nieobecny klucz bez niej jest zgłaszany w missingFields.
• Wartości text, image i barcode są rzutowane na łańcuch bez zmian.
• Wiązanie daty akceptuje DateTimeInterface, całkowity znacznik czasu Unix lub łańcuch w jednym z czterech jawnych formatów. Domyślnym formatem wyjściowym jest Y-m-d.
• Wiązanie liczby używa number_format(value, decimals, '.', ','). Liczba miejsc dziesiętnych pochodzi z format, domyślnie wynosi 2 i jest ograniczona do zakresu od 0 do 30.
• Wiązanie waluty poprzedza sformatowaną liczbę wartością format, domyślnie ustawiając prefiks na $.
• Wiązanie warunkowe emituje "true" lub "false" z rzutowania logicznego.

Przypadki brzegowe i tryby awarii

• backgroundPdf nigdy nie jest otwierany ani dereferencjonowany przez ten moduł. Jest to nieprzejrzysty łańcuch przekazywany do renderera.
• Wartość nienumeryczna powiązana z symbolem zastępczym typu Number lub Currency generuje ostrzeżenie; wartość jest rzutowana na łańcuch, a nie odrzucana.
• Łańcuchy daty są parsowane ściśle. Tokeny względne i w języku naturalnym (“now”, “+1 year”, “tomorrow”) nie pasują do żadnego akceptowanego formatu, więc generują ostrzeżenie, a surowa wartość jest przepuszczana bez zmian.
• Całkowita wartość daty jest odczytywana jako znacznik czasu Unix poprzez formę epoki @.
• Precyzja format typu Number spoza zakresu od 0 do 30, która dociera do bindera, jest odrzucana z ostrzeżeniem; binder wraca do domyślnej precyzji 2.
• W tym module nie zachodzi żadna operacja kryptograficzna, więc nie ma żadnego zachowania specyficznego dla trybu FIPS.

Zgodność ze standardami

Nie istnieje bezpośrednia powierzchnia specyfikacji PDF. Słowniki rozmiaru strony i orientacji są konwencjami NextPDF, a moduł emituje sformatowane wartości, a nie obiekty PDF. Ścisła lista dozwolonych łańcuchów daty akceptuje internetowy profil daty/czasu ISO 8601 zdefiniowany w RFC 3339 §5.6, obok daty kalendarzowej Y-m-d i dwóch lokalnych form daty i czasu. NextPDF dokumentuje możliwość odczytu tych formatów; nie rości sobie żadnej certyfikacji względem RFC 3339 ani ISO 8601.

Uwagi programistyczne

• TemplateParser i TemplateDataBinder są bezstanowe. Pojedyncza instancja jest wielokrotnego użytku i bezpieczna do współdzielenia między wiązaniami.
• Cztery obiekty wartości są final readonly; konstruuj je poprzez parser zamiast ręcznie dla danych produkcyjnych.
• validate zgłasza każdy błąd strukturalny w jednym przebiegu, podczas gdy parse wywołuje najpierw validate i zgłasza wyjątek z zagregowanym komunikatem. Użyj validate do informacji zwrotnej w stylu formularza, a parse do szybko zawodzącego wczytywania.
• Granice długości i precyzji są egzekwowane w parserze jako autorytatywna kontrola. TemplateDataBinder ponownie sprawdza precyzję liczby jako zabezpieczenie po stronie ujścia przed amplifikacją pamięci przez number_format.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię 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 (przewodnik po funkcji)
• Toc
• Merge