Render manifest: คำขอเรนเดอร์ที่พกพาได้

ภาพรวมโดยย่อ

render manifest คือคำอธิบายที่พกพาได้ของ สิ่งที่จะเรนเดอร์: input, template, ฟอนต์, locale, conformance profile, signature policy, output target และแฟล็ก Fast-Web-View ทุก transport จะสร้างและส่ง RenderManifest ตัวเดียวกัน ไม่ว่าจะเป็น command-line interface (CLI) การผสานรวมเฟรมเวิร์ก application programming interface (API) แบบ software-as-a-service (SaaS) หรือ stream connector ในอนาคต สัญญานี้ให้ผลลัพธ์กำหนดได้แน่นอน: manifest สองชุดที่เท่ากันจะ serialize เป็น JavaScript Object Notation (JSON) ที่เหมือนกันทุกไบต์ และแต่ละ manifest มี idempotency key ที่คำนวณได้ เพื่อให้ระบบปลายทางสามารถรู้จำและกำจัดการเรนเดอร์ที่ซ้ำกันได้

manifest เป็นสัญญาของ Core สัญญานี้กำหนดสคีมา ส่วนเอนจินและตัวประมวลผลสตรีมระดับพรีเมียมจะเป็นผู้ดำเนินการตามคำขอ

การติดตั้ง

composer require nextpdf/core:^3

การสร้าง manifest

ใช้ builder เป็นเส้นทางการสร้างที่เสถียร หรือใช้ RenderManifest::fromArray() สำหรับ manifest ที่ deserialize มาแล้ว คอนสตรักเตอร์โดยตรงเป็น @internal: ฟิลด์ทางเลือกใหม่จะถูกเพิ่มเข้ามาพร้อมค่าเริ่มต้น ดังนั้น builder และ fromArray() จะรองรับฟิลด์เหล่านั้นได้โดยไม่ทำให้จุดเรียกใช้เสียหาย

<?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`	ตัวระบุเชิงตรรกะที่เสถียรสำหรับผู้เรียกใช้ ซึ่งจะถูกสะท้อนกลับใน event และหลักฐานการรับคำขอ ไม่รวมอยู่ใน idempotency key
`idempotencyKey`	คีย์สำหรับกำจัดข้อมูลซ้ำที่กำหนดได้แน่นอน (ดูด้านล่าง)
`input`	แหล่งข้อมูลสำหรับการเรนเดอร์: payload แบบ inline, Uniform Resource Identifier (URI) หรือการอ้างอิง dataset พร้อม content hash
`template`	ส่วนหน้าสำหรับการเรนเดอร์และตัวระบุ template ที่ระบุหรือไม่ก็ได้
`fonts`	ชุดฟอนต์ที่ประกาศไว้ (ว่างเปล่าตามค่าเริ่มต้น)
`locale`	language tag ตาม BCP-47 (`en-US` ตามค่าเริ่มต้น)
`conformanceProfile`	ตัวระบุ profile ที่เสถียร (`none` ตามค่าเริ่มต้น)
`signaturePolicy`	ตัวระบุ policy ที่เสถียร (`none` ตามค่าเริ่มต้น)
`target`	คีย์ของ output object, รูปแบบ และ clobber policy
`linearize`	แฟล็ก Fast-Web-View ทำงานร่วมกับ linearization
`metadata`	แมป key/value แบบ scalar ที่ไม่ตีความภายใน ซึ่งจะถูกสะท้อนกลับใน event

คีย์ Idempotency

IdempotencyKey::derive() จะทำ hash เฉพาะส่วนย่อยของ manifest ที่ กำหนดผลการเรนเดอร์ เท่านั้น ได้แก่ template, content hash ของ input, ฟอนต์, locale, conformance, signature policy, แฟล็ก linearize และ target key โดยจงใจไม่รวม jobId และ metadata ดังนั้นคำขอสองรายการที่มี input ซึ่งกำหนดผลการเรนเดอร์เหมือนกัน รวมถึง output target เดียวกัน จะใช้คีย์ร่วมกันและสามารถกำจัดข้อมูลซ้ำได้ แม้ว่าตัวระบุงานหรือ metadata สำหรับการติดตามจะแตกต่างกัน ผู้เรียกใช้ยังสามารถระบุคีย์อย่างชัดเจนได้ โดย isDerived() จะรายงานว่าคีย์นั้นมาจากเส้นทางใด

การจัดเวอร์ชันของสคีมา

RenderManifest::SCHEMA_VERSION ตรึงเวอร์ชันของสคีมาไว้ (ปัจจุบันคือ 1.0) ภายใน major version เดียวกัน การพัฒนาจะเป็นแบบเพิ่มได้เท่านั้น: ตัวอ่านยอมรับคีย์ที่ไม่รู้จักจากสคีมา minor ที่ใหม่กว่าได้ แต่จะปฏิเสธ major version ที่ใหม่กว่า SchemaCompatibility::assertReadable() บังคับใช้กฎนี้ใน fromArray() และ canRead() / isForwardRead() ช่วยให้คุณทดสอบความเข้ากันได้โดยไม่โยนข้อยกเว้น

เนื่องจาก manifest เป็น data transfer object (DTO) แบบ readonly ที่มีคอนสตรักเตอร์เป็น @internal ให้สร้าง manifest ผ่าน builder หรือ fromArray() ฟิลด์ใหม่จะถูกเพิ่มเป็นพารามิเตอร์คอนสตรักเตอร์ที่มีค่าเริ่มต้น ดังนั้นการเพิ่มฟิลด์จึงไม่ทำให้จุดเรียกใช้เหล่านี้เสียหาย

การตรวจสอบความถูกต้อง

RenderManifestValidator::validate() ไม่โยนข้อยกเว้นและรวบรวมปัญหาทั้งหมด: จะคืนค่าปัญหาทุกอย่างที่พบ แทนที่จะล้มเหลวเมื่อพบปัญหาแรก โดยจะปฏิเสธคีย์ของ output ที่ไม่ปลอดภัย (การ traversal, พาธสัมบูรณ์, stream wrapper) แหล่ง input มากกว่าหนึ่งแหล่ง ตัวระบุ conformance profile ที่ไม่รู้จัก locale ตาม BCP-47 ที่ไม่ถูกต้อง และ clobber policy ที่ไม่ตรงกัน warnings() คืนค่าหมายเหตุเชิงคำแนะนำที่ไม่บล็อกการทำงาน

use NextPDF\Manifest\RenderManifestValidator;

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

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

การเรนเดอร์ manifest

SingleDocumentRenderer แปลง manifest หนึ่งชุดให้เป็น Portable Document Format (PDF) หนึ่งไฟล์โดยให้ผลลัพธ์กำหนดได้แน่นอน ทำงานแบบ pure: คืนค่าไบต์พร้อม sha-256 digest ของไบต์เหล่านั้น และไม่เขียนไฟล์ใด ดังนั้นการ staging และการ commit แบบ 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`	DTO แบบ readonly	`toArray()`, `toJson()`, `fromArray()`, `canonicalDigestInput()`, `SCHEMA_VERSION`	เสถียร	3.2.0
`RenderManifestBuilder`	builder	`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`	service	`render(): RenderOutcome`	เสถียร	3.2.0

fromArray() จะโยน RenderManifestException เมื่อไม่มีฟิลด์ที่จำเป็น หรือเมื่อเวอร์ชันของสคีมาไม่สามารถอ่านได้