Render manifest: yêu cầu kết xuất khả chuyển

Tổng quan nhanh

Render manifest là bản mô tả khả chuyển về những gì cần kết xuất: dữ liệu đầu vào, mẫu, phông chữ, locale, hồ sơ tuân thủ, chính sách chữ ký, đích đầu ra, và một cờ Fast-Web-View. Mọi transport đều dựng và gửi cùng một RenderManifest, dù đó là giao diện dòng lệnh (CLI), một tích hợp framework, một giao diện lập trình ứng dụng (API) software-as-a-service (SaaS), hay một stream connector trong tương lai. Hợp đồng này có tính tất định: hai manifest bằng nhau sẽ tuần tự hóa thành JavaScript Object Notation (JSON) giống hệt nhau đến từng byte, và mỗi manifest mang một khóa idempotency được suy ra để các hệ thống phía sau có thể nhận diện và loại trùng cùng một lần kết xuất.

Manifest là hợp đồng Core. Nó định nghĩa lược đồ; engine và stream processor premium thực thi yêu cầu.

Cài đặt

composer require nextpdf/core:^3

Dựng một manifest

Dùng builder làm cách dựng ổn định, hoặc dùng RenderManifest::fromArray() cho một manifest đã được giải tuần tự hóa. Hàm khởi tạo trực tiếp là @internal: các trường tùy chọn mới được thêm vào với giá trị mặc định, nên builder và fromArray() tiếp nhận chúng mà không phá vỡ các điểm gọi của bạn.

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

Các trường

Trường	Ý nghĩa
jobId	Định danh logic ổn định do phía gọi cung cấp, được lặp lại trong các sự kiện và biên nhận. Không tính vào khóa idempotency.
idempotencyKey	Khóa loại trùng có tính tất định (xem bên dưới).
input	Nguồn dữ liệu để kết xuất: payload nội tuyến, một Uniform Resource Identifier (URI), hoặc một tham chiếu tập dữ liệu kèm hash nội dung.
template	Front end kết xuất và định danh mẫu tùy chọn.
fonts	Tập phông chữ được khai báo (mặc định là rỗng).
locale	Một thẻ ngôn ngữ BCP-47 (mặc định là en-US).
conformanceProfile	Một định danh hồ sơ ổn định (mặc định là none).
signaturePolicy	Một định danh chính sách ổn định (mặc định là none).
target	Khóa đối tượng đầu ra, định dạng, và chính sách ghi đè.
linearize	Cờ Fast-Web-View; kết hợp với tuyến tính hóa.
metadata	Bản đồ key/value vô hướng mờ đục được lặp lại vào các sự kiện.

Khóa idempotency

IdempotencyKey::derive() chỉ băm tập con quyết định kết xuất của manifest: mẫu, hash nội dung đầu vào, phông chữ, locale, tuân thủ, chính sách chữ ký, cờ linearize, và khóa đích. Hàm này cố ý loại trừ jobId và metadata, nên hai yêu cầu có cùng các đầu vào quyết định kết xuất, bao gồm cả đích đầu ra, sẽ dùng chung một khóa và có thể bị loại trùng ngay cả khi định danh công việc hay metadata theo dõi của chúng khác nhau. Phía gọi cũng có thể cung cấp một khóa tường minh; isDerived() cho biết nó được tạo theo đường nào.

Đánh phiên bản lược đồ

RenderManifest::SCHEMA_VERSION cố định phiên bản lược đồ (hiện tại là 1.0). Trong cùng một phiên bản chính, lược đồ chỉ tiến hóa bằng cách bổ sung: bộ đọc dung nạp các khóa chưa biết từ một phiên bản phụ mới hơn, nhưng từ chối một phiên bản chính mới hơn. SchemaCompatibility::assertReadable() thực thi điều này trong fromArray(), còn canRead() / isForwardRead() cho bạn kiểm tra khả năng tương thích mà không ném ngoại lệ.

Vì manifest là một data transfer object (DTO) readonly với hàm khởi tạo là @internal, hãy dựng nó qua builder hoặc fromArray(). Các trường mới được thêm vào dưới dạng tham số khởi tạo có giá trị mặc định, nên việc thêm trường không phá vỡ các điểm gọi đó.

Kiểm tra hợp lệ

RenderManifestValidator::validate() không ném ngoại lệ và thu thập đầy đủ: nó trả về mọi vấn đề tìm thấy thay vì dừng ở lỗi đầu tiên. Nó từ chối các khóa đầu ra không an toàn (đi ngược thư mục, đường dẫn tuyệt đối, stream wrapper), nhiều hơn một nguồn đầu vào, định danh hồ sơ tuân thủ chưa biết, locale BCP-47 không hợp lệ, và trường hợp chính sách ghi đè không khớp. warnings() trả về các ghi chú khuyến nghị, không chặn.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Kết xuất một manifest

SingleDocumentRenderer biến một manifest thành một Portable Document Format (PDF) một cách tất định. Đây là thành phần thuần khiết: nó trả về các byte cùng với bản tóm tắt sha-256 của chúng và không ghi tệp nào, nên việc dàn dựng và commit chính xác một lần vẫn thuộc trách nhiệm của phía gọi (hoặc của 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;

Bề mặt API

Kiểu	Loại	Thành viên chính	Độ ổn định	Từ
RenderManifest	DTO readonly	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	ổn định	3.2.0
RenderManifestBuilder	builder	create(), with*(), linearized(), build()	ổn định	3.2.0
IdempotencyKey	value object	of(), derive(), equals(), isDerived()	ổn định	3.2.0
SchemaCompatibility	helper	canRead(), isForwardRead(), assertReadable()	ổn định	3.2.0
RenderManifestValidator	service	validate(), warnings()	ổn định	3.2.0
SingleDocumentRenderer	service	render(): RenderOutcome	ổn định	3.2.0

fromArray() ném RenderManifestException khi thiếu một trường bắt buộc hoặc phiên bản lược đồ không đọc được.