Render manifest: solicitação de renderização portátil

Visão geral

Um render manifest é a descrição portátil do que renderizar: entrada, template, fontes, locale, perfil de conformidade, política de assinatura, destino de saída e uma flag de Fast-Web-View. Todo transporte constrói e envia o mesmo RenderManifest, seja uma command-line interface (CLI), uma integração com framework, uma application programming interface (API) de software-as-a-service (SaaS) ou um futuro conector de stream. O contrato é determinístico: dois manifests iguais são serializados para JavaScript Object Notation (JSON) byte-idêntico, e cada manifest carrega uma chave de idempotência derivada para que os sistemas a jusante possam reconhecer e deduplicar a mesma renderização.

O manifest é um contrato do Core. Ele define o esquema; o engine e o processador de stream premium executam a solicitação.

Instalação

composer require nextpdf/core:^3

Construindo um manifest

Use o builder como caminho estável de construção ou use RenderManifest::fromArray() para um manifest desserializado. O construtor direto é @internal: novos campos opcionais são anexados com padrões, de modo que o builder e fromArray() os absorvem sem quebrar os pontos de chamada.

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

Campos

Campo	Significado
jobId	Identificador lógico estável para o chamador, repetido em eventos e recibos. Excluído da chave de idempotência.
idempotencyKey	Chave de deduplicação determinística (veja abaixo).
input	Fonte de dados da renderização: payload inline, um Uniform Resource Identifier (URI) ou uma referência de dataset com o hash do conteúdo.
template	Front end de renderização e identificador de template opcional.
fonts	Conjunto de fontes declarado (vazio por padrão).
locale	Uma tag de idioma BCP-47 (en-US por padrão).
conformanceProfile	Um identificador de perfil estável (none por padrão).
signaturePolicy	Um identificador de política estável (none por padrão).
target	Chave do objeto de saída, formato e política de sobrescrita.
linearize	Flag de Fast-Web-View; usada em conjunto com linearization.
metadata	Mapa escalar opaco de key/value, repetido em eventos.

Chave de idempotência

IdempotencyKey::derive() calcula hash apenas sobre o subconjunto que determina a renderização do manifest: template, hash do conteúdo de entrada, fontes, locale, conformidade, política de assinatura, a flag linearize e a chave do target. O cálculo exclui deliberadamente jobId e metadata, de modo que duas solicitações com entradas que determinam a renderização idênticas, incluindo o destino de saída, compartilham uma chave e podem ser deduplicadas mesmo quando seus identificadores de job ou metadados de rastreamento diferem. Um chamador também pode fornecer uma chave explícita; isDerived() informa qual caminho a produziu.

Versionamento de esquema

RenderManifest::SCHEMA_VERSION fixa a versão do esquema (atualmente 1.0). Dentro de uma versão major, a evolução é somente aditiva: um leitor tolera chaves desconhecidas de um esquema minor mais novo, mas rejeita uma versão major mais nova. SchemaCompatibility::assertReadable() aplica essa regra em fromArray(), e canRead() / isForwardRead() permitem testar a compatibilidade sem lançar exceções.

Como o manifest é um data transfer object (DTO) readonly cujo construtor é @internal, construa-o por meio do builder ou de fromArray(). Novos campos são adicionados como parâmetros do construtor com valores padrão, de modo que adicionar um campo não quebra esses pontos de chamada.

Validação

RenderManifestValidator::validate() não lança exceções e acumula todos os problemas: ele retorna todos os problemas que encontra em vez de falhar no primeiro. Ele rejeita chaves de saída inseguras (traversal, caminhos absolutos, stream wrappers), mais de uma fonte de entrada, um identificador de perfil de conformidade desconhecido, um locale BCP-47 inválido e uma incompatibilidade de política de sobrescrita. warnings() retorna avisos consultivos, não bloqueantes.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Renderizando um manifest

SingleDocumentRenderer renderiza um manifest como um único Portable Document Format (PDF) de forma determinística. É uma operação pura: retorna os bytes com seu digest sha-256 e não grava nenhum arquivo, de modo que o staging e o commit exactly-once permanecem responsabilidade do chamador (ou do processador de 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;

Superfície da API

Tipo	Categoria	Membros principais	Estabilidade	Desde
RenderManifest	DTO readonly	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	estável	3.2.0
RenderManifestBuilder	builder	create(), with*(), linearized(), build()	estável	3.2.0
IdempotencyKey	value object	of(), derive(), equals(), isDerived()	estável	3.2.0
SchemaCompatibility	helper	canRead(), isForwardRead(), assertReadable()	estável	3.2.0
RenderManifestValidator	service	validate(), warnings()	estável	3.2.0
SingleDocumentRenderer	service	render(): RenderOutcome	estável	3.2.0

fromArray() lança RenderManifestException quando falta um campo obrigatório ou quando a versão do esquema não é legível.