Render manifest（渲染請求清單）：可攜式渲染請求

快速概覽

render manifest 是一份對 要渲染什麼 的單一、可攜描述：包含輸入、範本、字型、locale、conformance profile、簽章政策、輸出目標，以及一個 Fast-Web-View 旗標。每個傳輸層（CLI、Framework（框架）整合、SaaS API、未來的 stream 連接器）都會建構並提交同一份 RenderManifest。這份合約是決定性的：兩份相等的 manifest 會序列化成完全相同的 JSON，而且每份 manifest 都帶有一個衍生的冪等鍵，讓相同的渲染能在下游被辨識並去重。

manifest 是一份 Core 合約。它定義結構；執行則由引擎與 premium stream 處理器負責。

安裝

composer require nextpdf/core:^3

建構 manifest

穩定的建構方式是 builder（建構器）；若 manifest 已反序列化，則使用 RenderManifest::fromArray()。原生建構子為 @internal：之後新增的選用欄位會帶著預設值附加到尾端，因此 builder 與 fromArray() 能吸收這些欄位，不會破壞你的呼叫端。

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

欄位

欄位	意義
jobId	由呼叫端提供的穩定邏輯 id，會在事件與回執中回傳。不納入冪等鍵的計算。
idempotencyKey	具決定性的去重鍵（見下文）。
input	渲染資料的來源：可以是 inline payload、URI，或一個 dataset 參考加上內容雜湊。
template	渲染前端，以及選用的 template id。
fonts	宣告的字型集合（預設為空）。
locale	BCP-47 語言標籤（預設為 en-US）。
conformanceProfile	穩定的 profile id（預設為 none）。
signaturePolicy	穩定的 policy id（預設為 none）。
target	輸出物件鍵、格式，以及覆寫政策。
linearize	Fast-Web-View 旗標；會與線性化組合運作。
metadata	一個不透明的純量 key/value map，會回傳到事件中。

冪等鍵

IdempotencyKey::derive() 只會對 manifest 中 決定渲染結果 的子集計算雜湊：包含範本、輸入內容雜湊、字型、locale、conformance、簽章政策、linearize 旗標，以及 target 鍵。它刻意排除 jobId 與 metadata，因此，只要兩個請求中決定渲染結果的輸入完全相同（包含輸出 target），就會共用同一個鍵並可被去重，即使它們的 job id 或追蹤 metadata 不同。呼叫端也可以明確提供一個鍵；isDerived() 會回報這個鍵是透過哪個途徑產生的。

結構版本控管

結構版本由 RenderManifest::SCHEMA_VERSION 固定（目前為 1.0）。在同一個主版本內，結構演進僅以新增方式進行：讀取器會容忍較新次版本結構中的未知鍵，但較新的主版本則會被拒絕。SchemaCompatibility::assertReadable() 會在 fromArray() 上強制執行這項規則，而 canRead() / isForwardRead() 則讓呼叫端能在不擲例外的情況下測試相容性。

由於 manifest 是 readonly DTO，且其建構子為 @internal，請透過 builder 或 fromArray() 建構。新欄位會以僅新增、帶有預設值的建構子參數形式加入，因此對這些呼叫端來說，新增欄位並不是破壞性變更。

驗證

RenderManifestValidator::validate() 不會擲出例外，並會收集所有問題：它會回傳找到的每個問題，而不是遇到第一個問題就失敗。它會拒絕不安全的輸出鍵（路徑穿越、絕對路徑、stream wrapper）、超過一個輸入來源、未知的 conformance profile id、無效的 BCP-47 locale，以及覆寫政策不符。warnings() 會回傳建議性且不阻擋執行的提示。

use NextPDF\Manifest\RenderManifestValidator;

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

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

渲染 manifest

SingleDocumentRenderer 會以決定性的方式將一份 manifest 轉成一份 PDF。它是純函式：會回傳位元組以及對應的 sha-256 摘要，而且不寫入任何檔案；因此暫存與恰好一次的提交仍由呼叫端（或 stream 處理器）負責。

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 介面

型別	種類	主要成員	穩定度	起始版本
RenderManifest	readonly DTO（唯讀資料傳輸物件）	toArray()、toJson()、fromArray()、canonicalDigestInput()、SCHEMA_VERSION	穩定	3.2.0
RenderManifestBuilder	建構器	create()、with*()、linearized()、build()	穩定	3.2.0
IdempotencyKey	value object（值物件）	of()、derive()、equals()、isDerived()	穩定	3.2.0
SchemaCompatibility	helper（輔助工具）	canRead()、isForwardRead()、assertReadable()	穩定	3.2.0
RenderManifestValidator	service（服務）	validate()、warnings()	穩定	3.2.0
SingleDocumentRenderer	服務	render(): RenderOutcome	穩定	3.2.0

fromArray() 會在必填欄位遺漏或結構版本無法讀取時擲出 RenderManifestException。