Template — Riferimento approfondito

In breve

Questo riferimento approfondito documenta lo schema JSON dei modelli accettato, ogni regola di validazione e l’esatto comportamento di formattazione per tipo del data binder. Il modulo analizza una definizione di modello, quindi associa i dati del chiamante a placeholder tipizzati. Emette stringhe formattate; non disegna oggetti PDF.

Disponibilità e licenze

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

Superficie API pubblica

Il modulo espone due servizi di ingresso e quattro value object immutabili. Ogni simbolo elencato di seguito è pubblico e stabile.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
TemplateParser::parse	string $json	Valida, poi costruisce la definizione	TemplateDefinition	InvalidArgumentException quando è presente un errore di validazione	Delega prima a validate.
TemplateParser::validate	string $json	Raccoglie tutti gli errori strutturali in un’unica passata	list<string> (vuota quando valido)	Non solleva mai eccezioni; un errore di decodifica JSON viene restituito come messaggio	Gate autoritativo per i limiti di lunghezza e precisione.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Confronta i placeholder senza distinzione tra maiuscole e minuscole e li formatta per tipo	BindingResult	Non solleva mai eccezioni; le anomalie diventano avvisi o campi mancanti	Usa il valore predefinito del placeholder quando la chiave è assente.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Memorizza la definizione analizzata	TemplateDefinition	TypeError in caso di tipo di argomento non corrispondente	Value object final readonly.
TemplateDefinition::getPlaceholder	string $name	Ricerca per nome senza distinzione tra maiuscole e minuscole	TemplatePlaceholder|null	Nessun errore; restituisce null quando assente	—
TemplateDefinition::requiredFields	nessuno	Raccoglie i nomi dei placeholder privi di valore predefinito	list<string>	Nessun errore	Un valore predefinito non vuoto rende opzionale un placeholder.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Memorizza una regione placeholder	TemplatePlaceholder	TypeError in caso di tipo di argomento non corrispondente	Le coordinate sono in punti a partire dall’angolo in alto a sinistra.
TemplatePlaceholder::matches	string $key	Confronto del nome senza distinzione tra maiuscole e minuscole	bool	Nessun errore	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Memorizza l’esito del binding	BindingResult	TypeError in caso di tipo di argomento non corrispondente	Value object final readonly.
BindingResult::isComplete	nessuno	Indica se ogni campo obbligatorio è stato associato	bool	Nessun errore	Vero quando missingFields è vuoto.
BindingResult::count	nessuno	Conta i placeholder associati con successo	int	Nessun errore	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Abbina un placeholder al suo valore formattato	BoundPlaceholder	TypeError in caso di tipo di argomento non corrispondente	Value object final readonly.
PlaceholderType	casi enum Text, Image, Barcode, Date, Number, Currency, Conditional	Tassonomia dei placeholder basata su stringhe	istanza enum	ValueError da from() per un valore sconosciuto	tryFrom() restituisce invece null.
PlaceholderType::requiresFormatting	nessuno	Indica se il tipo utilizza una stringa di formato	bool	Nessun errore	Vero per 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;
}

Contratto di comportamento

Forma JSON accettata:

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

Regole di validazione, tutte esposte da validate come messaggi e aggregate da parse in un’unica eccezione:

• name mancante o vuoto.
• pageSize al di fuori dell’allow-list, oppure orientation diverso da P o L.
• placeholders mancante, oppure un valore non-array.
• Per ciascun placeholder: nome mancante o vuoto; tipo non valido; x, y, width, height mancanti o non numerici; nome duplicato (senza distinzione tra maiuscole e minuscole).
• defaultValue: non stringa, più lungo di 4096 byte, oppure contenente un carattere di controllo ASCII.
• format: non stringa, più lungo di 256 byte, oppure contenente un carattere di controllo ASCII.
• Un format di un placeholder number che non è un intero non negativo, oppure che supera 30.

Semantica di binding (TemplateDataBinder::bind):

• Le chiavi dei dati vengono convertite in minuscolo per la corrispondenza senza distinzione tra maiuscole e minuscole rispetto ai nomi dei placeholder.
• Una chiave assente con un valore predefinito non vuoto associa il valore predefinito; una chiave assente che ne è priva viene segnalata in missingFields.
• I valori text, image e barcode vengono convertiti in stringa senza modifiche.
• Il binding delle date accetta un DateTimeInterface, un timestamp Unix intero, oppure una stringa in uno di quattro formati espliciti. Il formato di output predefinito è Y-m-d.
• Il binding dei numeri usa number_format(value, decimals, '.', ','). Il numero di decimali proviene da format, ha valore predefinito 2 ed è vincolato all’intervallo da 0 a 30.
• Il binding della valuta antepone al numero formattato format, con prefisso predefinito $.
• Il binding condizionale emette "true" o "false" da una conversione booleana.

Casi limite e modalità di errore

• backgroundPdf non viene mai aperto o dereferenziato da questo modulo. È una stringa opaca passata al renderer.
• Un valore non numerico associato a un placeholder Number o Currency produce un avviso; il valore viene convertito in stringa, non rifiutato.
• Le stringhe di data vengono analizzate in modo rigoroso. I token relativi e in linguaggio naturale («now», «+1 year», «tomorrow») non corrispondono ad alcun formato accettato, quindi generano un avviso e il valore grezzo viene passato inalterato.
• Un valore di data intero viene letto come timestamp Unix tramite la forma epoch @.
• Una precisione format di un Number al di fuori dell’intervallo da 0 a 30 che raggiunge il binder viene rifiutata con un avviso; il binder ricade sulla precisione predefinita di 2.
• In questo modulo non si verifica alcuna operazione crittografica, pertanto non esiste alcun comportamento specifico della modalità FIPS.

Conformità

Non esiste alcuna superficie diretta di specifica PDF. I vocabolari di dimensione della pagina e di orientamento sono convenzioni di NextPDF e il modulo emette valori formattati, non oggetti PDF. L’allow-list rigorosa per le date in formato stringa accetta il profilo Internet date/time di ISO 8601 definito in RFC 3339 §5.6, insieme a una data di calendario Y-m-d e a due forme di data-ora locale. NextPDF documenta la capacità di leggere questi formati; non rivendica alcuna certificazione rispetto a RFC 3339 o ISO 8601.

Note di sviluppo

• TemplateParser e TemplateDataBinder sono privi di stato. Una singola istanza è riutilizzabile e può essere condivisa in sicurezza tra più binding.
• I quattro value object sono final readonly; per gli input di produzione conviene costruirli tramite il parser anziché a mano.
• validate segnala ogni errore strutturale in un’unica passata, mentre parse chiama prima validate e solleva un’eccezione sul messaggio aggregato. Usare validate per il feedback in stile form e parse per un’ingestione fail-fast.
• I limiti di lunghezza e precisione sono applicati nel parser come gate autoritativo. TemplateDataBinder ricontrolla la precisione dei numeri come salvaguardia lato sink contro l’amplificazione di memoria di number_format.

Confine di pubblicazione

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

Vedere anche

• Template (guida alla funzionalità)
• Toc
• Merge