Plantilla

De un vistazo

NextPDF\Pro\Template analiza una definición de plantilla JSON y la convierte en un objeto de valor tipado, y vincula un array de datos asociativo a sus marcadores de posición con formato según el tipo. Produce un resultado de vinculación estructurado; no renderiza por sí mismo un PDF.

Disponibilidad y licencias

Esta función se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho de uso no carga las clases de la función. Ningún indicador de capacidad en tiempo de ejecución adicional restringe este módulo más allá de la licencia de nivel. Compare ediciones y obtenga una licencia.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

Una plantilla es un documento JSON que describe una configuración de página y una lista de marcadores de posición posicionados. TemplateParser valida el JSON y produce una TemplateDefinition inmutable. La validación es estricta: comprueba el tamaño de página frente a una lista de permitidos (A3–A6, B4, B5, Letter, Legal, Tabloid), la orientación (P o L) y el nombre, el tipo y las coordenadas numéricas de cada marcador de posición, y rechaza los nombres de marcador de posición duplicados.

TemplateDataBinder vincula un array de datos (que coincide sin distinguir mayúsculas con los nombres de los marcadores de posición) y formatea cada valor según PlaceholderType:

• Text / Image / Barcode — el valor se transfiere como una cadena.
• Date — formateado con el formato del marcador de posición (predeterminado Y-m-d), aceptando cadenas, marcas de tiempo Unix o DateTimeInterface.
• Number — number_format con los decimales del formato (predeterminado 2).
• Currency — número formateado con la cadena de formato como prefijo (predeterminado $).
• Conditional — "true" o "false" según la veracidad.

El resultado es un BindingResult que transporta los valores vinculados, la lista de campos requeridos ausentes y cualquier advertencia de formato. Convertir los valores vinculados en un PDF renderizado es responsabilidad del llamante, usando las API de documento y de writer de Core y la referencia opcional backgroundPdf.

Por qué funciona así

El analizador es la única compuerta autoritativa. Convierte JSON no confiable en una TemplateDefinition inmutable y totalmente tipada, y la vinculación se ejecuta entonces como una función pura de ese valor. Cada campo que más tarde alcanza un destino de formato está en una lista de permitidos y con longitud acotada en el momento del análisis. El tamaño de página, la orientación, la precisión numérica y los caracteres de control fallan todos aquí, no a mitad del renderizado. Las fechas en cadena se cotejan frente a un conjunto fijo de formatos canónicos, de modo que un valor como now o +1 year no puede hacer que la salida dependa del reloj del sistema. El módulo se detiene deliberadamente en un BindingResult y deja el renderizado, la resolución de rutas y la composición de fondo al llamante, lo que mantiene explícito el límite de confianza.

Contexto de diseño: Facturas y facturación electrónica.

Contrato de comportamiento

• Entrada. Una cadena JSON (TemplateParser) y un array de datos (TemplateDataBinder).
• Salida. TemplateDefinition del análisis; BindingResult de la vinculación.
• Validación. validate() devuelve una lista de errores legibles por humanos y nunca lanza; parse() lanza InvalidArgumentException cuando la validación falla.
• Datos ausentes. Un marcador de posición sin datos y con un valor predeterminado vacío se informa en missingFields; uno con un valor predeterminado no vacío usa el predeterminado.
• Determinismo. El análisis y la vinculación son funciones puras de sus entradas.

Superficie de la API pública

Tipo	Clase	Miembros clave
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	nombre, PlaceholderType $type, coordenadas, predeterminado, 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

Ejemplo de código — Inicio 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";
}

Ejemplo de código — Producció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
}

Casos límite y trampas

• Una cadena de fecha no analizable produce una advertencia y la cadena original se conserva, en lugar de lanzar.
• La cadena de formato de moneda se usa como prefijo literal (por ejemplo "$" o "EUR "), no como un identificador de configuración regional.
• backgroundPdf es una referencia de ruta transportada en la definición; este módulo no la abre, valida ni compone — esa es tarea del renderizador.
• Los nombres de los marcadores de posición coinciden sin distinguir mayúsculas; los nombres duplicados en el JSON son un error de validación.

Rendimiento

El análisis es una decodificación JSON más una validación estructural; la vinculación es lineal en el número de marcadores de posición. Consulte performance_budget.

Notas de seguridad

El JSON se decodifica con JSON_THROW_ON_ERROR y se valida frente a listas de permitidos fijas antes de construir una TemplateDefinition. El módulo no realiza E/S de archivo ni de red; la ruta backgroundPdf no se desreferencia aquí, así que el manejo de rutas y el control de acceso corresponden al renderizador.

Conformidad

Este módulo no tiene superficie directa de la especificación PDF: analiza una plantilla JSON y formatea valores. Los vocabularios de tamaño de página y de orientación son convenciones de NextPDF, no construcciones normativas de PDF.

Alternativa / respaldo de Core

No hay ninguna capa de definición de plantilla en Core. Para una construcción de documento totalmente imperativa, use directamente las API de documento y de writer del Core de código abierto. Consulte /modules/core/document/.

Nota sobre el límite de Enterprise

Este módulo define y vincula plantillas. No realiza orquestación de combinación de correspondencia, programación de trabajos por lotes ni renderizado; esas cuestiones quedan fuera del alcance y se gestionan en otro lugar.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API compatible. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Véase también

• Referencia de plantilla
• Toc
• Merge
• Modelo de documento de Core