Manifest renderowania: przenośne żądanie renderowania

W skrócie

Manifest renderowania to przenośny opis tego, co należy wyrenderować: danych wejściowych, szablonu, czcionek, ustawień regionalnych, profilu zgodności, zasad podpisu, celu wyjściowego oraz flagi Fast-Web-View. Każdy transport buduje i przesyła ten sam obiekt RenderManifest, niezależnie od tego, czy jest to interfejs wiersza poleceń (CLI), integracja z frameworkiem, interfejs programowania aplikacji (API) w modelu oprogramowania jako usługi (SaaS), czy przyszły łącznik strumieniowy. Kontrakt jest deterministyczny: dwa identyczne manifesty serializują się do identycznej bajt po bajcie notacji obiektowej JavaScript (JSON), a każdy manifest zawiera wyprowadzony klucz idempotentności, dzięki czemu systemy zależne mogą rozpoznać i zdeduplikować to samo renderowanie.

Manifest jest kontraktem modułu Core. Definiuje schemat; samo żądanie wykonują silnik oraz procesor strumieniowy Premium.

Instalacja

composer require nextpdf/core:^3

Budowanie manifestu

Skorzystaj z buildera jako stabilnej ścieżki tworzenia albo z metody RenderManifest::fromArray() dla zdeserializowanego manifestu. Bezpośredni konstruktor jest oznaczony jako @internal: nowe pola opcjonalne są dodawane z wartościami domyślnymi, więc builder oraz metoda fromArray() obsługują je bez naruszania miejsc wywołań w kodzie.

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

Pola

Pole	Znaczenie
jobId	Stabilny identyfikator logiczny nadawany przez wywołującego, powielany w zdarzeniach i potwierdzeniach. Wykluczony z klucza idempotentności.
idempotencyKey	Deterministyczny klucz deduplikacji (zobacz poniżej).
input	Źródło danych do renderowania: osadzony ładunek, ujednolicony identyfikator zasobu (URI) albo odwołanie do zbioru danych wraz ze skrótem treści.
template	Interfejs renderowania oraz opcjonalny identyfikator szablonu.
fonts	Deklarowany zestaw czcionek (domyślnie pusty).
locale	Znacznik języka BCP-47 (domyślnie en-US).
conformanceProfile	Stabilny identyfikator profilu (domyślnie none).
signaturePolicy	Stabilny identyfikator zasad (domyślnie none).
target	Klucz obiektu wyjściowego, format oraz zasady nadpisywania.
linearize	Flaga Fast-Web-View; współdziała z linearyzacją.
metadata	Nieinterpretowana mapa skalarnych par key/value powielana w zdarzeniach.

Klucz idempotentności

Metoda IdempotencyKey::derive() haszuje wyłącznie podzbiór manifestu określający renderowanie: szablon, skrót treści wejściowej, czcionki, ustawienia regionalne, zgodność, zasady podpisu, flagę linearyzacji oraz klucz celu. Celowo pomija pola jobId i metadata, dzięki czemu dwa żądania o identycznych danych określających renderowanie, wraz z celem wyjściowym, używają tego samego klucza i mogą zostać zdeduplikowane, nawet gdy różnią się identyfikatorami zadań lub metadanymi śledzenia. Wywołujący może również dostarczyć jawny klucz; metoda isDerived() wskazuje, która ścieżka go wytworzyła.

Wersjonowanie schematu

Stała RenderManifest::SCHEMA_VERSION ustala wersję schematu (obecnie 1.0). W ramach wersji głównej ewolucja jest wyłącznie addytywna: czytnik toleruje nieznane klucze z nowszej wersji pomocniczej schematu, ale odrzuca nowszą wersję główną. Metoda SchemaCompatibility::assertReadable() wymusza tę regułę w fromArray(), a metody canRead() / isForwardRead() pozwalają sprawdzić zgodność bez zgłaszania wyjątku.

Manifest jest obiektem transferu danych (DTO) typu readonly, a jego konstruktor jest oznaczony jako @internal, dlatego twórz go za pomocą buildera lub metody fromArray(). Nowe pola są dodawane jako parametry konstruktora z wartościami domyślnymi, więc dodanie pola nie narusza tych miejsc wywołań.

Walidacja

Metoda RenderManifestValidator::validate() nie zgłasza wyjątków i zbiera wszystkie problemy: zwraca każdy wykryty problem, zamiast przerywać przy pierwszym. Odrzuca niebezpieczne klucze wyjściowe (przechodzenie po katalogach, ścieżki bezwzględne, opakowania strumieni), więcej niż jedno źródło wejściowe, nieznany identyfikator profilu zgodności, nieprawidłowe ustawienia regionalne BCP-47 oraz niezgodność zasad nadpisywania. Metoda warnings() zwraca nieblokujące uwagi doradcze.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Renderowanie manifestu

Klasa SingleDocumentRenderer deterministycznie przekształca jeden manifest w jeden plik w formacie Portable Document Format (PDF). Działa bez efektów ubocznych: zwraca bajty wraz z ich skrótem sha-256 i nie zapisuje żadnego pliku, więc tymczasowe przechowywanie i zatwierdzanie w modelu exactly-once pozostają w gestii wywołującego (lub procesora strumieniowego).

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;

Powierzchnia API

Typ	Rodzaj	Kluczowe składowe	Stabilność	Od wersji
RenderManifest	DTO typu readonly	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	stabilny	3.2.0
RenderManifestBuilder	builder	create(), with*(), linearized(), build()	stabilny	3.2.0
IdempotencyKey	obiekt wartości	of(), derive(), equals(), isDerived()	stabilny	3.2.0
SchemaCompatibility	klasa pomocnicza	canRead(), isForwardRead(), assertReadable()	stabilny	3.2.0
RenderManifestValidator	usługa	validate(), warnings()	stabilny	3.2.0
SingleDocumentRenderer	usługa	render(): RenderOutcome	stabilny	3.2.0

Metoda fromArray() zgłasza wyjątek RenderManifestException, gdy brakuje wymaganego pola albo wersji schematu nie można odczytać.