Modelo

Visão geral

NextPDF\Pro\Template analisa uma definição de template em JSON em um objeto de valor tipado e vincula um array de dados associativo aos seus placeholders com formatação ciente do tipo. Ele produz um resultado de vinculação estruturado; ele não renderiza um PDF por si só.

Disponibilidade e licenciamento

Este recurso é distribuído no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes do recurso. Nenhum sinalizador adicional de capacidade em tempo de execução restringe este módulo além da licença de nível. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

Um template é um documento JSON que descreve a configuração de uma página e uma lista de placeholders posicionados. TemplateParser valida o JSON e produz uma TemplateDefinition imutável. A validação é estrita: ela verifica o tamanho da página contra uma allow-list (A3–A6, B4, B5, Letter, Legal, Tabloid), a orientação (P ou L) e o nome, o tipo e as coordenadas numéricas de cada placeholder, e rejeita nomes de placeholder duplicados.

TemplateDataBinder vincula um array de dados (correspondido sem distinção de maiúsculas e minúsculas aos nomes dos placeholders) e formata cada valor por PlaceholderType:

• Text / Image / Barcode — valor repassado como uma string.
• Date — formatado com o formato do placeholder (padrão Y-m-d), aceitando strings, timestamps Unix ou DateTimeInterface.
• Number — number_format com as casas decimais do formato (padrão 2).
• Currency — número formatado com a string de formato como prefixo (padrão $).
• Conditional — "true" ou "false" com base na veracidade (truthiness).

O resultado é um BindingResult que carrega os valores vinculados, a lista de campos obrigatórios ausentes e quaisquer avisos de formatação. Transformar os valores vinculados em um PDF renderizado é responsabilidade do chamador, usando as APIs de document e de writer do Core e a referência opcional backgroundPdf.

Por que funciona assim

O parser é o único portão autoritativo. Ele transforma JSON não confiável em uma TemplateDefinition imutável e totalmente tipada, e a vinculação então roda como uma função pura desse valor. Todo campo que mais tarde chega a um destino de formatação é allow-listed e limitado em comprimento no momento da análise. Tamanho de página, orientação, precisão numérica e caracteres de controle falham todos aqui, não no meio da renderização. As datas em string são correspondidas contra um conjunto fixo de formatos canônicos, de modo que um valor como now ou +1 year não pode fazer a saída depender do relógio do sistema. O módulo para deliberadamente em um BindingResult e deixa a renderização, a resolução de caminho e a composição de fundo para o chamador, o que mantém o limite de confiança explícito.

Contexto de design: Notas fiscais e faturamento eletrônico.

Contrato de comportamento

• Entrada. Uma string JSON (TemplateParser) e um array de dados (TemplateDataBinder).
• Saída. TemplateDefinition da análise; BindingResult da vinculação.
• Validação. validate() retorna uma lista de erros legíveis por humanos e nunca lança; parse() lança InvalidArgumentException quando a validação falha.
• Dados ausentes. Um placeholder sem dados e com um default vazio é reportado em missingFields; um com um default não vazio usa o default.
• Determinismo. A análise e a vinculação são funções puras de suas entradas.

Superfície da API pública

Tipo	Categoria	Membros principais
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	nome, PlaceholderType $type, coordenadas, default, formato
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

Exemplo de código — Início rápido

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

Exemplo de código — Produção

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

Casos extremos e armadilhas

• Uma string de data não analisável produz um aviso e a string original é mantida, em vez de lançar.
• A string de formato de moeda é usada como um prefixo literal (por exemplo "$" ou "EUR "), não um identificador de localidade.
• backgroundPdf é uma referência de caminho carregada na definição; este módulo não a abre, valida ou compõe — esse é o trabalho do renderizador.
• Os nomes de placeholder são correspondidos sem distinção de maiúsculas e minúsculas; nomes duplicados no JSON são um erro de validação.

Desempenho

A análise é uma decodificação JSON mais a validação estrutural; a vinculação é linear em relação à contagem de placeholders. Consulte performance_budget.

Notas de segurança

O JSON é decodificado com JSON_THROW_ON_ERROR e validado contra allow-lists fixas antes de uma TemplateDefinition ser construída. O módulo não realiza nenhum I/O de arquivo ou de rede; o caminho backgroundPdf não é desreferenciado aqui, portanto o tratamento de caminho e o controle de acesso pertencem ao renderizador.

Conformidade

Este módulo não tem superfície direta de especificação PDF: ele analisa um template JSON e formata valores. Os vocabulários de tamanho de página e de orientação são convenções do NextPDF, não construções PDF normativas.

Fallback / alternativa do Core

Não há camada de definição de template no Core. Para a construção de documentos totalmente imperativa, use diretamente as APIs de document e de writer do Core open source. Consulte /modules/core/document/.

Nota sobre o limite do Enterprise

Este módulo define e vincula templates. Ele não realiza orquestração de mala direta (mail-merge), agendamento de jobs em lote ou renderização; essas preocupações estão fora do escopo e são tratadas em outro lugar.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivo de runbook e prefixos de ticket estão fora do escopo.

Veja também

• Referência do Template
• Toc
• Merge
• Modelo de document do Core