レンダーマニフェスト：ポータブルなレンダー要求

概要

レンダーマニフェストは、何をレンダリングするか を表す、単一でポータブルな記述です。つまり、入力、テンプレート、フォント、ロケール、適合プロファイル、署名ポリシー、出力ターゲット、および Fast-Web-View フラグを含みます。すべてのトランスポート（CLI、フレームワーク統合、SaaS API、将来のストリームコネクター）は、同一の RenderManifest を構築して送信します。このコントラクトは決定論的です。等しい 2 つのマニフェストは、バイト単位で同一の JSON にシリアライズされます。また、マニフェストは導出された冪等性キーを保持するため、下流で同一のレンダーを認識して重複排除できます。

マニフェストは Core コントラクトです。マニフェストがスキーマを定義し、エンジンと Premium のストリームプロセッサーがその内容を実行します。

インストール

composer require nextpdf/core:^3

マニフェストの構築

安定した構築パスはビルダー（デシリアライズ済みのマニフェストでは RenderManifest::fromArray()）です。生のコンストラクターは @internal です。新しいオプションフィールドはデフォルト値付きで末尾に追加されるため、ビルダーと 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	レンダーデータの取得元。インラインペイロード、URI、またはデータセット参照とコンテンツハッシュのいずれかです。
template	レンダリング用フロントエンドと、省略可能なテンプレート ID。
fonts	宣言されたフォントセット（デフォルトは空）。
locale	BCP-47 言語タグ（デフォルトは en-US）。
conformanceProfile	安定したプロファイル ID（デフォルトは none）。
signaturePolicy	安定したポリシー ID（デフォルトは none）。
target	出力オブジェクトキー、フォーマット、および上書きポリシー。
linearize	Fast-Web-View フラグ。線形化と連携して機能します。
metadata	イベントにそのまま反映される、不透明なスカラー key/value マップ。

冪等性キー

IdempotencyKey::derive() は、マニフェストのうち レンダーを決定する サブセットだけをハッシュ化します。具体的には、テンプレート、入力コンテンツハッシュ、フォント、ロケール、適合、署名ポリシー、linearize フラグ、およびターゲットキーです。jobId と metadata は意図的に除外されます。そのため、レンダーを決定する入力（出力ターゲットを含む）が同一の 2 つの要求は、ジョブ ID やトラッキングメタデータが異なっていても、同じキーを共有して重複排除できます。呼び出し側が明示的なキーを指定することもできます。どちらのパスで生成されたかは isDerived() が報告します。

スキーマのバージョン管理

スキーマバージョンは RenderManifest::SCHEMA_VERSION によって固定されます（現在は 1.0）。進化はメジャーバージョン内では追加のみです。リーダーは新しいマイナースキーマの未知のキーを許容しますが、新しいメジャーバージョンは拒否します。SchemaCompatibility::assertReadable() は fromArray() でこれを強制し、canRead() / isForwardRead() を使うと、呼び出し側は例外をスローせずに互換性をテストできます。

マニフェストは readonly DTO であり、そのコンストラクターは @internal です。そのため、ビルダーまたは fromArray() を通じて構築してください。新しいフィールドは、デフォルト値を持つ追加のコンストラクターパラメーターとして追加されるため、フィールドの追加がそれらの呼び出し箇所にとって破壊的変更になることはありません。

検証

RenderManifestValidator::validate() は例外をスローせず、すべての問題を収集します。最初の問題で失敗するのではなく、検出したすべての問題のリストを返します。安全でない出力キー（トラバーサル、絶対パス、ストリームラッパー）、複数の入力ソース、未知の適合プロファイル ID、無効な BCP-47 ロケール、および上書きポリシーの不一致を拒否します。warnings() は、参考情報としてブロックしない注記を返します。

use NextPDF\Manifest\RenderManifestValidator;

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

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

マニフェストのレンダリング

SingleDocumentRenderer は、1 つのマニフェストを決定論的に 1 つの PDF へ変換します。これは純粋です。バイト列とその sha-256 ダイジェストを返すだけで、ファイルは書き込みません。そのため、ステージングと exactly-once コミットは呼び出し側（またはストリームプロセッサー）の責務のままです。

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	値オブジェクト	of(), derive(), equals(), isDerived()	安定	3.2.0
SchemaCompatibility	ヘルパー	canRead(), isForwardRead(), assertReadable()	安定	3.2.0
RenderManifestValidator	サービス	validate(), warnings()	安定	3.2.0
SingleDocumentRenderer	サービス	render(): RenderOutcome	安定	3.2.0

fromArray() は、必須フィールドが欠落している場合、またはスキーマバージョンを読み取れない場合に RenderManifestException をスローします。