Render manifest: permintaan render portabel

Sekilas

Render manifest adalah deskripsi portabel tentang apa yang harus dirender: input, templat, fon, locale, profil konformansi, kebijakan tanda tangan, target keluaran, dan flag Fast-Web-View. Setiap transport membangun dan mengirimkan RenderManifest yang sama, baik berupa command-line interface (CLI), integrasi framework, application programming interface (API) software-as-a-service (SaaS), maupun konektor stream di masa depan. Kontrak ini deterministik: dua manifest yang sama akan diserialisasi menjadi JavaScript Object Notation (JSON) yang identik per bita, dan setiap manifest membawa kunci idempotensi turunan sehingga sistem hilir dapat mengenali dan menghapus duplikasi render yang sama.

Manifest adalah kontrak Core. Manifest mendefinisikan skema; engine dan stream processor premium menjalankan permintaan.

Instalasi

composer require nextpdf/core:^3

Membangun manifest

Gunakan builder sebagai jalur konstruksi yang stabil, atau gunakan RenderManifest::fromArray() untuk manifest yang telah dideserialisasi. Konstruktor langsungnya bersifat @internal: bidang opsional baru ditambahkan dengan nilai standar, sehingga builder dan fromArray() dapat mengakomodasinya tanpa merusak titik panggilan Anda.

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

Bidang

Bidang	Arti
jobId	Pengidentifikasi logis yang stabil bagi pemanggil, disertakan kembali dalam peristiwa dan resi. Dikecualikan dari kunci idempotensi.
idempotencyKey	Kunci deduplikasi yang deterministik (lihat di bawah).
input	Sumber data render: payload inline, Uniform Resource Identifier (URI), atau referensi dataset disertai hash konten.
template	Renderer front end dan pengidentifikasi templat opsional.
fonts	Kumpulan fon yang dideklarasikan (standarnya kosong).
locale	Tag bahasa BCP-47 (standarnya en-US).
conformanceProfile	Pengidentifikasi profil yang stabil (standarnya none).
signaturePolicy	Pengidentifikasi kebijakan yang stabil (standarnya none).
target	Kunci objek keluaran, format, dan kebijakan penimpaan (clobber).
linearize	Flag Fast-Web-View; digunakan bersama linearisasi.
metadata	Peta key/value skalar yang bersifat buram dan disertakan kembali dalam peristiwa (event).

Kunci idempotensi

IdempotencyKey::derive() hanya menghitung hash atas subset manifest yang menentukan render: templat, hash konten input, fon, locale, konformansi, kebijakan tanda tangan, flag linearize, dan kunci target. Dengan sengaja, kunci ini mengecualikan jobId dan metadata, sehingga dua permintaan dengan input penentu render yang identik, termasuk target keluaran, berbagi kunci yang sama dan dapat dideduplikasi meskipun pengidentifikasi pekerjaan atau metadata pelacakannya berbeda. Pemanggil juga dapat menyediakan kunci eksplisit; isDerived() menunjukkan jalur mana yang menghasilkannya.

Pemversian skema

RenderManifest::SCHEMA_VERSION menetapkan versi skema (saat ini 1.0). Dalam satu versi mayor, evolusi hanya bersifat aditif: pembaca menoleransi kunci tak dikenal dari skema minor yang lebih baru, tetapi menolak versi mayor yang lebih baru. SchemaCompatibility::assertReadable() menegakkan hal ini di fromArray(), dan canRead() / isForwardRead() memungkinkan Anda menguji kompatibilitas tanpa melempar pengecualian.

Karena manifest adalah data transfer object (DTO) readonly yang konstruktornya bersifat @internal, bangunlah melalui builder atau fromArray(). Bidang baru ditambahkan sebagai parameter konstruktor dengan nilai standar, sehingga penambahan bidang tidak merusak titik panggilan yang ada.

Validasi

RenderManifestValidator::validate() tidak melempar pengecualian dan mengumpulkan semua masalah: ia mengembalikan setiap masalah yang ditemukannya alih-alih gagal pada masalah pertama. Ia menolak kunci keluaran yang tidak aman (traversal, jalur absolut, stream wrapper), lebih dari satu sumber input, pengidentifikasi profil konformansi yang tak dikenal, locale BCP-47 yang tidak valid, dan ketidakcocokan kebijakan penimpaan (clobber). warnings() mengembalikan catatan anjuran yang tidak memblokir.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Merender manifest

SingleDocumentRenderer mengubah satu manifest menjadi satu Portable Document Format (PDF) secara deterministik. Sifatnya murni: ia mengembalikan bita beserta digest sha-256-nya dan tidak menulis berkas apa pun, sehingga staging dan commit exactly-once tetap menjadi tanggung jawab pemanggil (atau stream processor).

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;

Permukaan API

Tipe	Jenis	Anggota utama	Stabilitas	Sejak
RenderManifest	DTO readonly	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	stabil	3.2.0
RenderManifestBuilder	builder	create(), with*(), linearized(), build()	stabil	3.2.0
IdempotencyKey	value object	of(), derive(), equals(), isDerived()	stabil	3.2.0
SchemaCompatibility	helper	canRead(), isForwardRead(), assertReadable()	stabil	3.2.0
RenderManifestValidator	service	validate(), warnings()	stabil	3.2.0
SingleDocumentRenderer	service	render(): RenderOutcome	stabil	3.2.0

fromArray() melempar RenderManifestException ketika bidang wajib tidak ada atau versi skemanya tidak dapat dibaca.