Pro edição

Template — Referência Profunda

Em resumo

Esta referência profunda documenta o esquema JSON de template aceito, cada regra de validação e o comportamento exato de formatação por tipo do vinculador de dados. O módulo analisa uma definição de template e depois vincula os dados do chamador a placeholders tipados. Ele emite strings formatadas; não desenha objetos PDF.

Disponibilidade & licenciamento

Este recurso é entregue no NextPDF Pro (nextpdf/pro) e ativa 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 de capacidade em tempo de execução restringe este módulo. Compare as edições e obtenha uma licença.

Superfície da API pública

O módulo expõe dois serviços de ponto de entrada e quatro objetos de valor imutáveis. Todo símbolo abaixo é público e estável.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`TemplateParser::parse`	`string $json`	Valida e depois constrói a definição	`TemplateDefinition`	`InvalidArgumentException` quando há qualquer erro de validação	Delega primeiro para `validate`.
`TemplateParser::validate`	`string $json`	Coleta todos os erros estruturais em uma única passagem	`list<string>` (vazia quando válida)	Nunca lança; uma falha de decodificação JSON é retornada como mensagem	Gate autoritativo para os limites de comprimento e precisão.
`TemplateDataBinder::bind`	`TemplateDefinition $template`, `array<string,mixed> $data`	Faz a correspondência de placeholders sem distinção de maiúsculas e minúsculas e formata por tipo	`BindingResult`	Nunca lança; anomalias viram avisos ou campos ausentes	Usa o valor padrão de um placeholder quando a chave está ausente.
`TemplateDefinition::__construct`	`string $name`, `string $pageSize`, `string $orientation`, `list<TemplatePlaceholder> $placeholders`, `string $backgroundPdf = ''`	Armazena a definição analisada	`TemplateDefinition`	`TypeError` em uma incompatibilidade de tipo de argumento	Objeto de valor final readonly.
`TemplateDefinition::getPlaceholder`	`string $name`	Busca por nome sem distinção de maiúsculas e minúsculas	`TemplatePlaceholder\|null`	Sem falha; retorna `null` quando ausente	—
`TemplateDefinition::requiredFields`	nenhum	Coleta os nomes dos placeholders que não têm valor padrão	`list<string>`	Sem falha	Um padrão não vazio marca um placeholder como opcional.
`TemplatePlaceholder::__construct`	`string $name`, `PlaceholderType $type`, `float $x`, `float $y`, `float $width`, `float $height`, `string $defaultValue = ''`, `string $format = ''`	Armazena uma região de placeholder	`TemplatePlaceholder`	`TypeError` em uma incompatibilidade de tipo de argumento	As coordenadas são pontos a partir do canto superior esquerdo.
`TemplatePlaceholder::matches`	`string $key`	Comparação de nome sem distinção de maiúsculas e minúsculas	`bool`	Sem falha	—
`BindingResult::__construct`	`list<BoundPlaceholder> $bindings`, `list<string> $missingFields`, `list<string> $warnings`	Armazena o resultado da vinculação	`BindingResult`	`TypeError` em uma incompatibilidade de tipo de argumento	Objeto de valor final readonly.
`BindingResult::isComplete`	nenhum	Informa se todos os campos obrigatórios foram vinculados	`bool`	Sem falha	Verdadeiro quando `missingFields` está vazia.
`BindingResult::count`	nenhum	Conta os placeholders vinculados com sucesso	`int`	Sem falha	—
`BoundPlaceholder::__construct`	`TemplatePlaceholder $placeholder`, `string $formattedValue`, `mixed $rawValue`	Emparelha um placeholder com seu valor formatado	`BoundPlaceholder`	`TypeError` em uma incompatibilidade de tipo de argumento	Objeto de valor final readonly.
`PlaceholderType`	casos de enum `Text`, `Image`, `Barcode`, `Date`, `Number`, `Currency`, `Conditional`	Taxonomia de placeholder respaldada por string	instância de enum	`ValueError` de `from()` em um valor desconhecido	`tryFrom()` retorna `null` em vez disso.
`PlaceholderType::requiresFormatting`	nenhum	Informa se o tipo consome uma string de formato	`bool`	Sem falha	Verdadeiro para `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;
}

Contrato de comportamento

Formato JSON aceito:

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

Regras de validação, todas expostas por validate como mensagens e agregadas por parse em uma única exceção:

name ausente ou vazio.
pageSize fora da allow-list, ou orientation diferente de P ou L.
placeholders ausente, ou um valor que não seja um array.
Por placeholder: nome ausente ou vazio; tipo inválido; x, y, width, height ausentes ou não numéricos; nome duplicado (sem distinção de maiúsculas e minúsculas).
defaultValue: não string, com mais de 4096 bytes, ou carregando um caractere de controle ASCII.
format: não string, com mais de 256 bytes, ou carregando um caractere de controle ASCII.
Um format de placeholder number que não seja um inteiro não negativo, ou que exceda 30.

Semântica de vinculação (TemplateDataBinder::bind):

As chaves de dados são convertidas para minúsculas para a correspondência sem distinção de maiúsculas e minúsculas com os nomes dos placeholders.
Uma chave ausente com um padrão não vazio vincula o padrão; uma chave ausente sem um é relatada em missingFields.
Valores de texto, imagem e barcode são convertidos em string sem alteração.
A vinculação de data aceita um DateTimeInterface, um timestamp Unix inteiro, ou uma string em um de quatro formatos explícitos. O formato de saída padrão é Y-m-d.
A vinculação de número usa number_format(value, decimals, '.', ','). A contagem de decimais vem de format, tem padrão 2 e é limitada ao intervalo de 0 a 30.
A vinculação de moeda prefixa o número formatado com format, tendo $ como prefixo padrão.
A vinculação condicional emite "true" ou "false" a partir de uma conversão booleana.

Casos extremos & modos de falha

O backgroundPdf nunca é aberto ou desreferenciado por este módulo. Ele é uma string opaca entregue ao renderizador.
Um valor não numérico vinculado a um placeholder Number ou Currency produz um aviso; o valor é convertido em string (string-cast), não rejeitado.
As strings de data são analisadas estritamente. Tokens relativos e de linguagem natural (“now”, “+1 year”, “tomorrow”) não correspondem a nenhum formato aceito, então geram aviso e o valor bruto passa adiante sem alteração.
Um valor de data inteiro é lido como um timestamp Unix por meio da forma de época @.
Uma precisão de format de Number fora do intervalo de 0 a 30 que chegue ao vinculador é rejeitada com um aviso; o vinculador recorre à precisão padrão de 2.
Nenhuma operação criptográfica ocorre neste módulo, portanto não há comportamento específico de modo FIPS.

Conformidade

Não existe superfície direta de especificação PDF. Os vocabulários de tamanho de página e de orientação são convenções do NextPDF, e o módulo emite valores formatados, não objetos PDF. A allow-list estrita de datas em string aceita o perfil de data/hora da Internet do ISO 8601 definido no RFC 3339 §5.6, junto de uma data de calendário Y-m-d e duas formas locais de data-hora. O NextPDF documenta a capacidade de ler esses formatos; não reivindica nenhuma certificação em relação ao RFC 3339 ou ao ISO 8601.

Notas de desenvolvimento

TemplateParser e TemplateDataBinder são sem estado. Uma única instância é reutilizável e segura para compartilhar entre vinculações.
Os quatro objetos de valor são final readonly; construa-os por meio do parser em vez de manualmente para entrada de produção.
validate relata todo erro estrutural em uma única passagem, enquanto parse chama validate primeiro e lança sobre a mensagem agregada. Use validate para feedback em estilo de formulário e parse para ingestão fail-fast.
Os limites de comprimento e precisão são impostos no parser como o gate autoritativo. TemplateDataBinder reverifica a precisão do número como uma proteção do lado do sink contra a amplificação de memória do number_format.

Limite de publicação

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