Template

In breve

NextPDF\Pro\Template analizza una definizione di template JSON in un value object tipizzato e associa un array di dati associativo ai suoi placeholder con formattazione consapevole del tipo. Produce un risultato di binding strutturato; non renderizza di per sé un PDF.

Disponibilità e licenza

Questa funzionalità è fornita con NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di tier Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Nessun ulteriore flag di capability di runtime applica il gate a questo modulo oltre alla licenza di tier. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Un template è un documento JSON che descrive l’impostazione di una pagina e una lista di placeholder posizionati. TemplateParser valida il JSON e produce un TemplateDefinition immutabile. La validazione è rigorosa: verifica la dimensione della pagina rispetto a un’allow-list (A3–A6, B4, B5, Letter, Legal, Tabloid), l’orientamento (P o L) e il nome, il tipo e le coordinate numeriche di ciascun placeholder, e rifiuta i nomi di placeholder duplicati.

TemplateDataBinder associa un array di dati (corrisposto senza distinzione tra maiuscole e minuscole ai nomi dei placeholder) e formatta ogni valore in base a PlaceholderType:

• Text / Image / Barcode — il valore viene passato così com’è come stringa.
• Date — formattato con il formato del placeholder (default Y-m-d), accettando stringhe, timestamp Unix o DateTimeInterface.
• Number — number_format con i decimali dal formato (default 2).
• Currency — numero formattato con la stringa di formato come prefisso (default $).
• Conditional — "true" o "false" in base alla veridicità.

Il risultato è un BindingResult che trasporta i valori associati, la lista dei campi obbligatori mancanti ed eventuali avvisi di formattazione. La trasformazione dei valori associati in un PDF renderizzato è responsabilità del chiamante, usando le API document e writer di Core e il riferimento opzionale backgroundPdf.

Perché funziona così

Il parser è l’unico gate autoritativo. Trasforma il JSON non attendibile in un TemplateDefinition immutabile e completamente tipizzato, e il binding viene poi eseguito come funzione pura di quel value object. Ogni campo che in seguito raggiunge un sink di formattazione è messo in allow-list e limitato in lunghezza in fase di analisi. Dimensione della pagina, orientamento, precisione numerica e caratteri di controllo falliscono tutti qui, non a metà del rendering. Le date in forma di stringa sono corrisposte rispetto a un insieme fisso di formati canonici, così un valore come now o +1 year non può far dipendere l’output dall’orologio di sistema. Il modulo si ferma deliberatamente a un BindingResult e lascia al chiamante il rendering, la risoluzione dei percorsi e il compositing dello sfondo, mantenendo così esplicito il confine di fiducia.

Contesto di progettazione: Fatture e fatturazione elettronica.

Contratto di comportamento

• Input. Una stringa JSON (TemplateParser) e un array di dati (TemplateDataBinder).
• Output. TemplateDefinition dall’analisi; BindingResult dal binding.
• Validazione. validate() restituisce una lista di errori leggibili e non solleva mai eccezioni; parse() solleva InvalidArgumentException quando la validazione fallisce.
• Dati mancanti. Un placeholder privo di dati e con un default vuoto è riportato in missingFields; uno con un default non vuoto usa il default.
• Determinismo. L’analisi e il binding sono funzioni pure dei loro input.

Superficie API pubblica

Tipo	Genere	Membri chiave
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	name, PlaceholderType $type, coordinate, default, format
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

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e accorgimenti

• Una stringa di data non analizzabile produce un avviso e la stringa originale viene mantenuta, anziché sollevare un’eccezione.
• La stringa di formato della valuta viene usata come prefisso letterale (ad esempio "$" o "EUR "), non come identificatore di locale.
• backgroundPdf è un riferimento a un percorso trasportato nella definizione; questo modulo non lo apre, non lo valida e non lo compone — è compito del renderer.
• I nomi dei placeholder sono corrisposti senza distinzione tra maiuscole e minuscole; nomi duplicati nel JSON costituiscono un errore di validazione.

Prestazioni

L’analisi è una singola decodifica JSON più la validazione strutturale; il binding è lineare nel conteggio dei placeholder. Vedere performance_budget.

Note di sicurezza

Il JSON viene decodificato con JSON_THROW_ON_ERROR e validato rispetto ad allow-list fisse prima che venga costruito un TemplateDefinition. Il modulo non esegue alcun I/O di file o di rete; il percorso backgroundPdf non viene dereferenziato qui, pertanto la gestione del percorso e il controllo degli accessi spettano al renderer.

Conformità

Questo modulo non ha alcuna superficie diretta di specifica PDF: analizza un template JSON e formatta i valori. I vocabolari di dimensione della pagina e di orientamento sono convenzioni di NextPDF, non costrutti PDF normativi.

Fallback / alternativa di Core

Non esiste un livello di definizione di template di Core. Per una costruzione di documenti completamente imperativa, usare direttamente le API document e writer di Core open source. Vedere /modules/core/document/.

Nota sul confine Enterprise

Questo modulo definisce e associa i template. Non esegue l’orchestrazione di mail-merge, la pianificazione dei batch job o il rendering; tali aspetti sono fuori ambito e sono gestiti altrove.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Template reference
• Toc
• Merge
• Modello document di Core