Template — Referencia detallada

Visión general

Esta referencia detallada documenta el esquema JSON de plantilla aceptado, cada regla de validación y el comportamiento exacto de formato por tipo del vinculador de datos. El módulo analiza una definición de plantilla y luego vincula los datos del invocador a marcadores de posición tipados. Emite cadenas con formato; no dibuja objetos PDF.

Disponibilidad y licencia

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Comparar ediciones y obtener una licencia.

Superficie de la API pública

El módulo expone dos servicios de punto de entrada y cuatro objetos de valor inmutables. Cada símbolo a continuación es público y estable.

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
TemplateParser::parse	string $json	Valida y luego construye la definición	TemplateDefinition	InvalidArgumentException cuando hay algún error de validación	Delega primero en validate.
TemplateParser::validate	string $json	Reúne todos los errores estructurales en una sola pasada	list<string> (vacía cuando es válida)	Nunca lanza; un fallo de decodificación JSON se devuelve como mensaje	Verificación autoritativa de los límites de longitud y precisión.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Empareja los marcadores de posición sin distinción de mayúsculas y da formato según el tipo	BindingResult	Nunca lanza; las anomalías se convierten en advertencias o campos faltantes	Usa el valor por defecto de un marcador de posición cuando la clave está ausente.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Almacena la definición analizada	TemplateDefinition	TypeError ante una discordancia de tipo de argumento	Objeto de valor final de solo lectura.
TemplateDefinition::getPlaceholder	string $name	Búsqueda por nombre sin distinción de mayúsculas	TemplatePlaceholder|null	Sin fallo; devuelve null cuando está ausente	—
TemplateDefinition::requiredFields	ninguno	Reúne los nombres de los marcadores de posición que no tienen valor por defecto	list<string>	Sin fallo	Un valor por defecto no vacío marca un marcador de posición como opcional.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Almacena una región de marcador de posición	TemplatePlaceholder	TypeError ante una discordancia de tipo de argumento	Las coordenadas son puntos desde la esquina superior izquierda.
TemplatePlaceholder::matches	string $key	Comparación de nombre sin distinción de mayúsculas	bool	Sin fallo	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Almacena el resultado de la vinculación	BindingResult	TypeError ante una discordancia de tipo de argumento	Objeto de valor final de solo lectura.
BindingResult::isComplete	ninguno	Informa si se vinculó cada campo obligatorio	bool	Sin fallo	Verdadero cuando missingFields está vacío.
BindingResult::count	ninguno	Cuenta los marcadores de posición vinculados con éxito	int	Sin fallo	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Empareja un marcador de posición con su valor con formato	BoundPlaceholder	TypeError ante una discordancia de tipo de argumento	Objeto de valor final de solo lectura.
PlaceholderType	casos de enum Text, Image, Barcode, Date, Number, Currency, Conditional	Taxonomía de marcadores de posición respaldada por cadenas	instancia de enum	ValueError de from() ante un valor desconocido	tryFrom() devuelve null en su lugar.
PlaceholderType::requiresFormatting	ninguno	Informa si el tipo consume una cadena de formato	bool	Sin fallo	Verdadero 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 comportamiento

Forma JSON aceptada:

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

Reglas de validación, todas expuestas por validate como mensajes y agregadas por parse en una sola excepción:

• name ausente o vacío.
• pageSize fuera de la lista de permitidos, u orientation distinta de P o L.
• placeholders ausente, o un valor que no es un array.
• Por marcador de posición: nombre ausente o vacío; tipo no válido; x, y, width, height ausentes o no numéricos; nombre duplicado (sin distinción de mayúsculas).
• defaultValue: no es una cadena, supera los 4096 bytes o contiene un carácter de control ASCII.
• format: no es una cadena, supera los 256 bytes o contiene un carácter de control ASCII.
• Un format de un marcador de posición number que no es un entero no negativo, o que supera 30.

Semántica de la vinculación (TemplateDataBinder::bind):

• Las claves de datos se convierten a minúsculas para el emparejamiento sin distinción de mayúsculas frente a los nombres de los marcadores de posición.
• Una clave ausente con un valor por defecto no vacío vincula el valor por defecto; una clave ausente sin él se informa en missingFields.
• Los valores de texto, imagen y código de barras se convierten a cadena sin cambios.
• La vinculación de fechas acepta un DateTimeInterface, una marca de tiempo Unix entera o una cadena en uno de cuatro formatos explícitos. El formato de salida por defecto es Y-m-d.
• La vinculación de números usa number_format(value, decimals, '.', ','). La cantidad de decimales procede de format, es 2 por defecto y está acotada al rango de 0 a 30.
• La vinculación de moneda antepone format al número con formato, con $ como prefijo por defecto.
• La vinculación condicional emite "true" o "false" a partir de una conversión booleana.

Casos límite y modos de fallo

• Este módulo nunca abre ni desreferencia backgroundPdf. Es una cadena opaca entregada al renderizador.
• Un valor no numérico vinculado a un marcador de posición Number o Currency produce una advertencia; el valor se convierte a cadena, no se rechaza.
• Las cadenas de fecha se analizan de forma estricta. Los tokens relativos y de lenguaje natural («now», «+1 year», «tomorrow») no coinciden con ningún formato aceptado, por lo que advierten y el valor en bruto pasa sin cambios.
• Un valor de fecha entero se lee como una marca de tiempo Unix mediante la forma de época @.
• Una precisión de format de Number fuera del rango de 0 a 30 que llega al vinculador se rechaza con una advertencia; el vinculador recurre a la precisión por defecto de 2.
• En este módulo no ocurre ninguna operación criptográfica, por lo que no hay comportamiento específico del modo FIPS.

Conformidad

No existe una superficie directa de especificación de PDF. Los vocabularios de tamaño de página y orientación son convenciones de NextPDF, y el módulo emite valores con formato, no objetos PDF. La lista estricta de permitidos para fechas en cadena acepta el perfil de fecha/hora de Internet de ISO 8601 definido en RFC 3339 §5.6, junto con una fecha de calendario Y-m-d y dos formas locales de fecha y hora. NextPDF documenta la capacidad de leer estos formatos; no reclama ninguna certificación frente a RFC 3339 ni ISO 8601.

Notas de desarrollo

• TemplateParser y TemplateDataBinder no tienen estado. Una sola instancia es reutilizable y segura para compartir entre vinculaciones.
• Los cuatro objetos de valor son final readonly; conviene construirlos a través del analizador en lugar de a mano para entradas de producción.
• validate informa cada error estructural en una sola pasada, mientras que parse llama primero a validate y lanza según el mensaje agregado. Conviene usar validate para retroalimentación tipo formulario y parse para una ingesta con fallo rápido.
• Los límites de longitud y precisión se aplican en el analizador como verificación autoritativa. TemplateDataBinder vuelve a comprobar la precisión de los números como salvaguarda del lado del sumidero frente a la amplificación de memoria de number_format.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de los manuales de operación y los prefijos de ticket quedan fuera de alcance.

Véase también

• Template (guía de la capacidad)
• Toc
• Merge