Pro редакция

Template — глубокий справочник

Кратко

Этот углублённый справочник документирует принимаемую схему JSON-шаблона, каждое правило валидации и точное поведение форматирования по типам у биндера данных. Модуль разбирает определение шаблона, затем привязывает данные вызывающей стороны к типизированным плейсхолдерам. Он выдаёт отформатированные строки; он не рисует объекты PDF.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется с лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы возможности. Никакой флаг возможности времени выполнения не гейтирует этот модуль. Сравните редакции и получите лицензию.

Поверхность публичного API

Модуль предоставляет два входных сервиса и четыре неизменяемых объекта-значения. Каждый символ ниже является публичным и стабильным.

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
`TemplateParser::parse`	`string $json`	Валидирует, затем строит определение	`TemplateDefinition`	`InvalidArgumentException`, если присутствует любая ошибка валидации	Сначала делегирует `validate`.
`TemplateParser::validate`	`string $json`	Собирает все структурные ошибки за один проход	`list<string>` (пустой, когда валидно)	Никогда не бросает; сбой декодирования JSON возвращается как сообщение	Авторитетный гейт для границ длины и точности.
`TemplateDataBinder::bind`	`TemplateDefinition $template`, `array<string,mixed> $data`	Сопоставляет плейсхолдеры без учёта регистра и форматирует по типу	`BindingResult`	Никогда не бросает; аномалии становятся предупреждениями или отсутствующими полями	Использует значение плейсхолдера по умолчанию, когда ключ отсутствует.
`TemplateDefinition::__construct`	`string $name`, `string $pageSize`, `string $orientation`, `list<TemplatePlaceholder> $placeholders`, `string $backgroundPdf = ''`	Хранит разобранное определение	`TemplateDefinition`	`TypeError` при несоответствии типа аргумента	Финальный readonly объект-значение.
`TemplateDefinition::getPlaceholder`	`string $name`	Поиск по имени без учёта регистра	`TemplatePlaceholder\|null`	Без сбоя; возвращает `null`, когда отсутствует	—
`TemplateDefinition::requiredFields`	нет	Собирает имена плейсхолдеров без значения по умолчанию	`list<string>`	Без сбоя	Непустое значение по умолчанию делает плейсхолдер необязательным.
`TemplatePlaceholder::__construct`	`string $name`, `PlaceholderType $type`, `float $x`, `float $y`, `float $width`, `float $height`, `string $defaultValue = ''`, `string $format = ''`	Хранит одну область плейсхолдера	`TemplatePlaceholder`	`TypeError` при несоответствии типа аргумента	Координаты — точки от верхнего левого угла.
`TemplatePlaceholder::matches`	`string $key`	Сравнение имён без учёта регистра	`bool`	Без сбоя	—
`BindingResult::__construct`	`list<BoundPlaceholder> $bindings`, `list<string> $missingFields`, `list<string> $warnings`	Хранит результат биндинга	`BindingResult`	`TypeError` при несоответствии типа аргумента	Финальный readonly объект-значение.
`BindingResult::isComplete`	нет	Сообщает, было ли привязано каждое обязательное поле	`bool`	Без сбоя	True, когда `missingFields` пуст.
`BindingResult::count`	нет	Считает успешно привязанные плейсхолдеры	`int`	Без сбоя	—
`BoundPlaceholder::__construct`	`TemplatePlaceholder $placeholder`, `string $formattedValue`, `mixed $rawValue`	Связывает плейсхолдер с его отформатированным значением	`BoundPlaceholder`	`TypeError` при несоответствии типа аргумента	Финальный readonly объект-значение.
`PlaceholderType`	случаи enum `Text`, `Image`, `Barcode`, `Date`, `Number`, `Currency`, `Conditional`	Строковая таксономия плейсхолдеров	экземпляр enum	`ValueError` из `from()` при неизвестном значении	`tryFrom()` возвращает `null` вместо этого.
`PlaceholderType::requiresFormatting`	нет	Сообщает, потребляет ли тип строку формата	`bool`	Без сбоя	True для `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;
}

Контракт поведения

Принимаемая форма 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" }
  ]
}

Правила валидации, все выдаваемые validate как сообщения и агрегируемые parse в одно исключение:

Отсутствующее или пустое name.
pageSize вне списка допустимых значений или orientation, не равный P или L.
Отсутствующий placeholders или значение, не являющееся массивом.
На каждый плейсхолдер: отсутствующее или пустое имя; недопустимый тип; отсутствующие или нечисловые x, y, width, height; дублирующееся имя (без учёта регистра).
defaultValue: не строка, длиннее 4096 байт или содержащий управляющий символ ASCII.
format: не строка, длиннее 256 байт или содержащий управляющий символ ASCII.
format плейсхолдера number, не являющийся неотрицательным целым числом или превышающий 30.

Семантика биндинга (TemplateDataBinder::bind):

Ключи данных приводятся к нижнему регистру для сопоставления без учёта регистра с именами плейсхолдеров.
Отсутствующий ключ с непустым значением по умолчанию привязывает значение по умолчанию; отсутствующий ключ без него сообщается в missingFields.
Значения text, image и barcode приводятся к строке без изменений.
Биндинг даты принимает DateTimeInterface, целочисленную Unix-метку времени или строку в одном из четырёх явных форматов. Формат вывода по умолчанию — Y-m-d.
Биндинг числа использует number_format(value, decimals, '.', ','). Количество знаков после запятой берётся из format, по умолчанию 2 и ограничено диапазоном от 0 до 30.
Биндинг валюты добавляет к отформатированному числу префикс format, со значением префикса по умолчанию $.
Биндинг conditional выдаёт "true" или "false" из приведения к булеву типу.

Граничные случаи и режимы отказа

backgroundPdf никогда не открывается и не разыменовывается этим модулем. Это непрозрачная строка, передаваемая отрисовщику.
Нечисловое значение, привязанное к плейсхолдеру Number или Currency, порождает предупреждение; значение приводится к строке, а не отклоняется.
Строки даты разбираются строго. Относительные и естественно-языковые токены (“now”, “+1 year”, “tomorrow”) не соответствуют ни одному принятому формату, поэтому они выдают предупреждение, и сырое значение проходит насквозь без изменений.
Целочисленное значение даты читается как Unix-метка времени через форму эпохи @.
Точность format для Number вне диапазона от 0 до 30, дошедшая до биндера, отклоняется с предупреждением; биндер откатывается к точности по умолчанию, равной 2.
В этом модуле не выполняется никаких криптографических операций, поэтому специфичного для режима FIPS поведения нет.

Соответствие

Прямой поверхности спецификации PDF не существует. Словари размера страницы и ориентации — это соглашения NextPDF, и модуль выдаёт отформатированные значения, а не объекты PDF. Строгий список допустимых строковых дат принимает интернет-профиль даты/времени ISO 8601, определённый в RFC 3339 §5.6, наряду с календарной датой Y-m-d и двумя формами локальных даты-времени. NextPDF документирует возможность читать эти форматы; он не заявляет о какой-либо сертификации по RFC 3339 или ISO 8601.

Заметки по разработке

TemplateParser и TemplateDataBinder не имеют состояния. Один экземпляр можно переиспользовать и безопасно разделять между биндингами.
Четыре объекта-значения являются final readonly; для производственного ввода создавайте их через парсер, а не вручную.
validate сообщает о каждой структурной ошибке за один проход, тогда как parse сначала вызывает validate и бросает исключение с агрегированным сообщением. Используйте validate для обратной связи в стиле формы и parse для строгого приёма с ранним отказом.
Границы длины и точности принудительно применяются в парсере как авторитетный гейт. TemplateDataBinder перепроверяет точность числа как защиту на стороне приёмника от усиления потребления памяти в number_format.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.