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。