Manifest di rendering: la richiesta di rendering portabile

In sintesi

Un manifest di rendering è una descrizione unica e portabile di ciò che va sottoposto a rendering: input, template, font, locale, profilo di conformità, criterio di firma, destinazione di output e flag Fast-Web-View. Ogni trasporto (CLI, integrazione con un framework, un’API SaaS, futuro connettore di flusso) costruisce lo stesso RenderManifest e lo invia. Il contratto è deterministico: due manifest uguali vengono serializzati in JSON byte per byte identico e ogni manifest porta con sé una chiave di idempotenza derivata, così che lo stesso rendering possa essere riconosciuto e deduplicato a valle.

Il manifest è un contratto Core. Definisce lo schema; il motore e lo stream processor premium ne eseguono il contenuto.

Installazione

composer require nextpdf/core:^3

Costruzione di un manifest

Il percorso di costruzione stabile è il builder (oppure RenderManifest::fromArray() per un manifest deserializzato). Il costruttore grezzo è @internal: i nuovi campi facoltativi vengono aggiunti in coda con valori predefiniti, così che il builder e fromArray() possano assorbirli senza compromettere i punti di chiamata esistenti.

examples/manifest/build.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Manifest\OutputObjectKey;
use NextPDF\Manifest\RenderManifestBuilder;
use NextPDF\Manifest\TemplateRef;

$manifest = RenderManifestBuilder::create('invoice-2026-0001')
    ->withInlineInput('<h1>Invoice 2026-0001</h1>')
    ->withTemplate(TemplateRef::html())
    ->withOutputKey(OutputObjectKey::file('invoices', '2026-0001.pdf'))
    ->withLocale('en-US')
    ->linearized()
    ->build();

// Deterministic, canonical-key-order JSON — equal manifests are byte-identical.
$json = $manifest->toJson();

Campi

Campo	Significato
jobId	ID logico stabile per il chiamante, riportato in eventi e ricevute. Escluso dalla chiave di idempotenza.
idempotencyKey	Chiave di deduplicazione deterministica (vedere sotto).
input	Origine dei dati di rendering: payload inline, URI oppure riferimento a un dataset più l’hash del contenuto.
template	Front end di rendering e id di template facoltativo.
fonts	Insieme dichiarato di font (vuoto per impostazione predefinita).
locale	Un tag di lingua BCP-47 (en-US per impostazione predefinita).
conformanceProfile	Un ID di profilo stabile (none per impostazione predefinita).
signaturePolicy	Un ID di criterio stabile (none per impostazione predefinita).
target	Chiave dell’oggetto di output, formato e criterio di sovrascrittura.
linearize	Flag Fast-Web-View; si integra con la linearizzazione.
metadata	Una mappa opaca di valori scalari key/value riportata negli eventi.

Chiave di idempotenza

IdempotencyKey::derive() calcola l’hash solo sul sottoinsieme del manifest che determina il rendering: template, hash del contenuto di input, font, locale, conformità, criterio di firma, flag linearize e chiave di destinazione. Esclude deliberatamente jobId e metadata, così due richieste con input identici che determinano il rendering — destinazione di output compresa — condividono una chiave e possono essere deduplicate, anche quando differiscono per job id o metadati di tracciamento. Il chiamante può anche fornire una chiave esplicita; isDerived() indica quale percorso l’ha prodotta.

Versionamento dello schema

La versione dello schema è fissata da RenderManifest::SCHEMA_VERSION (attualmente 1.0). L’evoluzione avviene solo per aggiunta all’interno di una versione major: un reader tollera chiavi sconosciute provenienti da uno schema minor più recente, mentre una versione major più recente viene rifiutata. SchemaCompatibility::assertReadable() applica questa regola in fromArray(), mentre canRead() / isForwardRead() permettono al chiamante di verificare la compatibilità senza sollevare eccezioni.

Poiché il manifest è un DTO readonly con costruttore @internal, costruirlo tramite builder o fromArray(). I nuovi campi vengono introdotti come parametri additivi del costruttore e con valore predefinito; di conseguenza, l’aggiunta di un campo non costituisce una modifica incompatibile per quei punti di chiamata.

Convalida

RenderManifestValidator::validate() non solleva eccezioni e raccoglie tutti i problemi: restituisce l’elenco completo dei problemi individuati anziché interrompersi al primo. Rifiuta chiavi di output non sicure (traversal, percorsi assoluti, stream wrapper), più di una sorgente di input, un ID di profilo di conformità sconosciuto, un locale BCP-47 non valido e un’incongruenza nel criterio di sovrascrittura. warnings() restituisce note informative non bloccanti.

use NextPDF\Manifest\RenderManifestValidator;

$problems = (new RenderManifestValidator())->validate($manifest);

if ($problems !== []) {
    // Each entry is a stable, human-readable problem string.
}

Rendering di un manifest

SingleDocumentRenderer trasforma un manifest in un PDF in modo deterministico. È puro: restituisce i byte e il relativo digest sha-256 e non scrive alcun file. Di conseguenza, staging e commit exactly-once restano a carico del chiamante (o dello stream processor).

use NextPDF\Manifest\Render\SingleDocumentRenderer;
use NextPDF\Manifest\Render\StandaloneDocumentFactory;

$renderer = new SingleDocumentRenderer(new StandaloneDocumentFactory());
$outcome  = $renderer->render($manifest);

$bytes  = $outcome->bytes;
$digest = $outcome->sha256;
$pages  = $outcome->pageCount;

Superficie dell’API

Tipo	Genere	Membri principali	Stabilità	Da
RenderManifest	DTO readonly	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	stabile	3.2.0
RenderManifestBuilder	builder	create(), with*(), linearized(), build()	stabile	3.2.0
IdempotencyKey	value object	of(), derive(), equals(), isDerived()	stabile	3.2.0
SchemaCompatibility	helper	canRead(), isForwardRead(), assertReadable()	stabile	3.2.0
RenderManifestValidator	servizio	validate(), warnings()	stabile	3.2.0
SingleDocumentRenderer	servizio	render(): RenderOutcome	stabile	3.2.0

fromArray() solleva RenderManifestException se manca un campo obbligatorio o se la versione dello schema non è leggibile.