Pro редакция

Template

Краткий обзор

NextPDF\Pro\Template разбирает определение шаблона JSON в типизированный объект-значение и привязывает ассоциативный массив данных к его плейсхолдерам с форматированием по типам. Он формирует структурированный результат привязки; сам он не отрисовывает PDF.

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

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

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

Шаблон — это документ JSON, описывающий настройку страницы и список позиционированных плейсхолдеров. TemplateParser валидирует JSON и формирует неизменяемый TemplateDefinition. Валидация строгая: она проверяет размер страницы по списку допустимых значений (A3–A6, B4, B5, Letter, Legal, Tabloid), ориентацию (P или L), а также имя, тип и числовые координаты каждого плейсхолдера и отклоняет дублирующиеся имена плейсхолдеров.

TemplateDataBinder привязывает массив данных (сопоставляемый без учёта регистра к именам плейсхолдеров) и форматирует каждое значение по PlaceholderType:

Text / Image / Barcode — значение проходит насквозь как строка.
Date — форматируется по формату плейсхолдера (по умолчанию Y-m-d), принимает строки, Unix-метки времени или DateTimeInterface.
Number — number_format с числом знаков из формата (по умолчанию 2).
Currency — число, отформатированное со строкой формата в качестве префикса (по умолчанию $).
Conditional — "true" или "false" на основе истинности.

Результат — BindingResult, несущий привязанные значения, список отсутствующих обязательных полей и любые предупреждения форматирования. Превращение привязанных значений в отрисованный PDF — ответственность вызывающей стороны, с использованием API документа и writer из Core и необязательной ссылки backgroundPdf.

Почему это работает именно так

Парсер — единственный авторитетный шлюз. Он превращает недоверенный JSON в неизменяемый, полностью типизированный TemplateDefinition, после чего привязка выполняется как чистая функция от этого значения. Каждое поле, которое затем достигает точки форматирования, при разборе внесено в список допустимых значений и ограничено по длине. Размер страницы, ориентация, точность чисел и управляющие символы отсекаются здесь, а не посреди отрисовки. Строковые даты сопоставляются с фиксированным набором канонических форматов, поэтому значение вроде now или +1 year не может поставить вывод в зависимость от системных часов. Модуль намеренно останавливается на BindingResult и оставляет отрисовку, разрешение путей и наложение фона вызывающей стороне, что делает границу доверия явной.

Проектный контекст: Invoices and e-invoicing.

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

Вход. Строка JSON (TemplateParser) и массив данных (TemplateDataBinder).
Выход. TemplateDefinition от разбора; BindingResult от привязки.
Валидация. validate() возвращает список человекочитаемых ошибок и никогда не бросает исключение; parse() бросает InvalidArgumentException, когда валидация не проходит.
Отсутствующие данные. Плейсхолдер без данных и с пустым значением по умолчанию сообщается в missingFields; плейсхолдер с непустым значением по умолчанию использует значение по умолчанию.
Детерминизм. Разбор и привязка — чистые функции своих входных данных.

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

Тип	Вид	Ключевые члены
`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`	имя, `PlaceholderType $type`, координаты, значение по умолчанию, формат
`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`

Пример кода — быстрый старт

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

Пример кода — продакшн

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

Граничные случаи и подводные камни

Неразбираемая строка даты даёт предупреждение, и исходная строка сохраняется, а не вызывает исключение.
Строка формата валюты используется как литеральный префикс (например "$" или "EUR "), а не как идентификатор локали.
backgroundPdf — это ссылка на путь, несомая в определении; этот модуль не открывает, не валидирует и не компонует его — это работа отрисовщика.
Имена плейсхолдеров сопоставляются без учёта регистра; дублирующиеся имена в JSON — это ошибка валидации.

Производительность

Разбор — это одно декодирование JSON плюс структурная валидация; привязка линейна по числу плейсхолдеров. См. performance_budget.

Замечания по безопасности

JSON декодируется с JSON_THROW_ON_ERROR и валидируется по фиксированным спискам допустимых значений до построения TemplateDefinition. Модуль не выполняет файлового или сетевого ввода-вывода; путь backgroundPdf здесь не разыменовывается, поэтому обработка пути и контроль доступа относятся к отрисовщику.

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

У этого модуля нет прямой поверхности спецификации PDF: он разбирает шаблон JSON и форматирует значения. Словари размера страницы и ориентации — это соглашения NextPDF, а не нормативные конструкции PDF.

Резервный режим Core / альтернатива

Слоя определения шаблонов в Core нет. Для полностью императивного построения документа используйте API документа и writer из открытого Core напрямую. См. /modules/core/document/.

Замечание о границе Enterprise

Этот модуль определяет и привязывает шаблоны. Он не выполняет оркестрацию слияния писем (mail-merge), планирование пакетных заданий или отрисовку; эти задачи вне области охвата и обрабатываются в другом месте.

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

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