Render-Manifest: die portable Rendering-Anfrage

Auf einen Blick

Ein Render-Manifest ist eine einzelne, portable Beschreibung davon, was gerendert werden soll: Eingabe, Template, Schriften, Locale, Konformitätsprofil, Signaturrichtlinie, Ausgabeziel und ein Fast-Web-View-Flag. Jeder Transport (CLI, eine Framework-Integration, eine SaaS-API, ein künftiger Stream-Connector) erstellt dasselbe RenderManifest und reicht es ein. Der Vertrag ist deterministisch: Zwei identische Manifeste werden zu bytegleichem JSON serialisiert, und jedes Manifest trägt einen abgeleiteten Idempotenzschlüssel, sodass derselbe Rendervorgang nachgelagert erkannt und dedupliziert werden kann.

Das Manifest ist ein Core-Vertrag. Es definiert das Schema; die Engine und der Premium-Stream-Prozessor führen es aus.

Installation

composer require nextpdf/core:^3

Ein Manifest bauen

Der stabile Weg zur Erstellung ist der Builder (oder RenderManifest::fromArray() für ein deserialisiertes Manifest). Der direkte Konstruktor ist @internal: Neue optionale Felder werden mit Standardwerten angehängt, sodass der Builder und fromArray() sie aufnehmen, ohne bestehende Aufrufstellen zu brechen.

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

Felder

Feld	Bedeutung
jobId	Aufruferstabile logische ID, die in Events und Belegen widergespiegelt wird. Vom Idempotenzschlüssel ausgeschlossen.
idempotencyKey	Deterministischer Dedup-Schlüssel (siehe unten).
input	Quelle der Renderdaten: Inline-Payload, eine URI oder eine Dataset-Referenz plus Content-Hash.
template	Das Rendering-Frontend und eine optionale Template-ID.
fonts	Deklarierter Schriftsatz (standardmäßig leer).
locale	Ein BCP-47-Sprach-Tag (standardmäßig en-US).
conformanceProfile	Eine stabile Profil-ID (standardmäßig none).
signaturePolicy	Eine stabile Richtlinien-ID (standardmäßig none).
target	Ausgabeobjekt-Schlüssel, Format und Clobber-Richtlinie.
linearize	Fast-Web-View-Flag; kombinierbar mit Linearisierung.
metadata	Eine opake, skalare key/value-Map, die in Events widergespiegelt wird.

Idempotenzschlüssel

IdempotencyKey::derive() hasht nur die für das Rendering maßgebliche Teilmenge des Manifests: Template, Content-Hash der Eingabe, Schriften, Locale, Konformität, Signaturrichtlinie, das Linearisierungs-Flag und den Zielschlüssel. Es schließt jobId und metadata bewusst aus, sodass zwei Anfragen mit identischen, für das Rendering maßgeblichen Eingaben, einschließlich des Ausgabeziels, einen Schlüssel teilen und dedupliziert werden können, selbst wenn sich ihre Job-IDs oder Tracking-Metadaten unterscheiden. Ein Aufrufer kann auch einen expliziten Schlüssel angeben; isDerived() meldet, auf welchem Weg er erzeugt wurde.

Schema-Versionierung

Die Schema-Version wird durch RenderManifest::SCHEMA_VERSION festgelegt (derzeit 1.0). Innerhalb einer Hauptversion erfolgt die Entwicklung rein additiv: Ein Leser toleriert unbekannte Schlüssel aus einem neueren Minor-Schema, während eine neuere Hauptversion abgelehnt wird. SchemaCompatibility::assertReadable() erzwingt dies bei fromArray(), und canRead() / isForwardRead() ermöglichen es Aufrufern, die Kompatibilität zu testen, ohne eine Ausnahme zu werfen.

Da das Manifest ein readonly-DTO mit @internal-Konstruktor ist, erstellen Sie es über den Builder oder fromArray(). Neue Felder werden als additive Konstruktorparameter mit Standardwerten ergänzt, sodass eine Felderweiterung für diese Aufrufstellen keine brechende Änderung ist.

Validierung

RenderManifestValidator::validate() wirft keine Ausnahmen und sammelt alle Probleme: Es gibt eine Liste aller gefundenen Probleme zurück, statt beim ersten zu scheitern. Es lehnt unsichere Ausgabeschlüssel (Traversal, absolute Pfade, Stream-Wrapper), mehr als eine Eingabequelle, eine unbekannte Konformitätsprofil-ID, eine ungültige BCP-47-Locale und eine Clobber-Richtlinien-Inkonsistenz ab. warnings() gibt empfehlende, nicht blockierende Hinweise zurück.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Ein Manifest rendern

SingleDocumentRenderer erzeugt aus einem Manifest deterministisch ein PDF. Er arbeitet ohne Seiteneffekte: Er gibt Bytes plus deren sha-256-Digest zurück und schreibt keine Datei. Dadurch bleiben Staging und Exactly-once-Commit Sache des Aufrufers (oder des Stream-Prozessors).

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-Oberfläche

Typ	Art	Wichtige Mitglieder	Stabilität	Seit
RenderManifest	readonly-DTO	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	stabil	3.2.0
RenderManifestBuilder	Builder	create(), with*(), linearized(), build()	stabil	3.2.0
IdempotencyKey	Value Object	of(), derive(), equals(), isDerived()	stabil	3.2.0
SchemaCompatibility	Helfer	canRead(), isForwardRead(), assertReadable()	stabil	3.2.0
RenderManifestValidator	Service	validate(), warnings()	stabil	3.2.0
SingleDocumentRenderer	Service	render(): RenderOutcome	stabil	3.2.0

fromArray() wirft RenderManifestException, wenn ein Pflichtfeld fehlt oder die Schema-Version nicht lesbar ist.