Rendermanifest: het overdraagbare renderverzoek

In een oogopslag

Een rendermanifest is de overdraagbare beschrijving van wat er gerenderd moet worden: invoer, sjabloon, lettertypen, locale, conformiteitsprofiel, handtekeningbeleid, uitvoerdoel en een Fast-Web-View-vlag. Elk transport bouwt en verstuurt hetzelfde RenderManifest, of dat nu een command-line interface (CLI), een framework-integratie, een software-as-a-service (SaaS)-application programming interface (API) of een toekomstige streamconnector is. Het contract is deterministisch: twee gelijke manifesten worden geserialiseerd naar byte-identieke JavaScript Object Notation (JSON), en elk manifest bevat een afgeleide idempotentiesleutel zodat downstreamsystemen dezelfde render kunnen herkennen en dedupliceren.

Het manifest is een Core-contract. Het definieert het schema; de engine en de premium stream processor voeren het verzoek uit.

Installatie

composer require nextpdf/core:^3

Een manifest bouwen

Gebruik de builder als de stabiele manier om een manifest te construeren, of gebruik RenderManifest::fromArray() voor een gedeserialiseerd manifest. De directe constructor is @internal: nieuwe optionele velden worden toegevoegd met standaardwaarden, zodat de builder en fromArray() deze opnemen zonder je aanroeplocaties te breken.

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();

Velden

Veld	Betekenis
jobId	Voor de aanroeper stabiele logische identificatie, herhaald in gebeurtenissen en ontvangstbewijzen. Uitgesloten van de idempotentiesleutel.
idempotencyKey	Deterministische deduplicatiesleutel (zie hieronder).
input	Renderdatabron: inline payload, een Uniform Resource Identifier (URI) of een datasetreferentie plus content-hash.
template	De rendering-front-end en een optionele sjabloonidentificatie.
fonts	Gedeclareerde lettertypenset (standaard leeg).
locale	Een BCP-47-taaltag (standaard en-US).
conformanceProfile	Een stabiele profielidentificatie (standaard none).
signaturePolicy	Een stabiele beleidsidentificatie (standaard none).
target	Sleutel, formaat en overschrijfbeleid van het uitvoerobject.
linearize	Fast-Web-View-vlag; werkt samen met linearisatie.
metadata	Ondoorzichtige scalaire key/value-map die in gebeurtenissen wordt herhaald.

Idempotentiesleutel

IdempotencyKey::derive() berekent alleen een hash over de renderbepalende subset van het manifest: sjabloon, content-hash van de invoer, lettertypen, locale, conformiteit, handtekeningbeleid, de linearize-vlag en de target-sleutel. Het sluit bewust jobId en metadata uit, zodat twee verzoeken met identieke renderbepalende invoer, inclusief het uitvoerdoel, een sleutel delen en gededupliceerd kunnen worden, zelfs wanneer hun job-identificaties of trackingmetadata verschillen. Een aanroeper kan ook een expliciete sleutel opgeven; isDerived() geeft aan via welk pad de sleutel is ontstaan.

Schemaversiebeheer

RenderManifest::SCHEMA_VERSION legt de schemaversie vast (momenteel 1.0). Binnen een hoofdversie is evolutie uitsluitend additief: een reader tolereert onbekende sleutels uit een nieuwer minorschema, maar wijst een nieuwere hoofdversie af. SchemaCompatibility::assertReadable() dwingt dit af in fromArray(), en met canRead() / isForwardRead() kun je de compatibiliteit testen zonder een exception te werpen.

Omdat het manifest een readonly data transfer object (DTO) is waarvan de constructor @internal is, bouw je het via de builder of fromArray(). Nieuwe velden worden toegevoegd als constructorparameters met een standaardwaarde, zodat het toevoegen van een veld je aanroeplocaties niet breekt.

Validatie

RenderManifestValidator::validate() werpt geen exceptions en verzamelt alles: het retourneert elk probleem dat het aantreft in plaats van bij het eerste probleem te falen. Het wijst onveilige uitvoersleutels af (traversal, absolute paden, stream wrappers), meer dan een invoerbron, een onbekende conformiteitsprofielidentificatie, een ongeldige BCP-47-locale en een niet-overeenkomend overschrijfbeleid. warnings() retourneert adviserende, niet-blokkerende opmerkingen.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Een manifest renderen

SingleDocumentRenderer zet een manifest deterministisch om naar Portable Document Format (PDF). Deze renderer is puur: hij retourneert bytes plus hun sha-256-digest en schrijft geen bestand, zodat staging en exactly-once commit de verantwoordelijkheid blijven van de aanroeper (of van de 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;

API-oppervlak

Type	Soort	Belangrijkste members	Stabiliteit	Sinds
RenderManifest	readonly DTO	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	stabiel	3.2.0
RenderManifestBuilder	builder	create(), with*(), linearized(), build()	stabiel	3.2.0
IdempotencyKey	value object	of(), derive(), equals(), isDerived()	stabiel	3.2.0
SchemaCompatibility	helper	canRead(), isForwardRead(), assertReadable()	stabiel	3.2.0
RenderManifestValidator	service	validate(), warnings()	stabiel	3.2.0
SingleDocumentRenderer	service	render(): RenderOutcome	stabiel	3.2.0

fromArray() werpt RenderManifestException wanneer een verplicht veld ontbreekt of de schemaversie onleesbaar is.