İşleme bildirimi: taşınabilir bir işleme isteği

Bir bakışta

İşleme bildirimi, neyin işleneceğinin taşınabilir açıklamasıdır: girdi, şablon, yazı tipleri, yerel ayar, uyumluluk profili, imza politikası, çıktı hedefi ve Fast-Web-View bayrağı. İster bir komut satırı arayüzü (CLI), ister bir çerçeve entegrasyonu, ister bir hizmet olarak yazılım (SaaS) API’si, isterse gelecekteki bir akış bağlayıcısı olsun, her aktarım aynı RenderManifest nesnesini oluşturur ve gönderir. Sözleşme deterministiktir: birbirine eşit iki bildirim, bayt düzeyinde özdeş JavaScript Object Notation (JSON) biçiminde serileştirilir ve her bildirim türetilmiş bir idempotency anahtarı taşır; böylece alt sistemler aynı işlemeyi tanıyıp yinelenenleri ayıklayabilir.

Bildirim, bir Core sözleşmesidir. Şemayı bildirim tanımlar; isteği motor ve premium akış işlemcisi yürütür.

Kurulum

composer require nextpdf/core:^3

Bir bildirim oluşturma

Kararlı oluşturma yolu için oluşturucuyu kullanın veya seri biçimden çözülmüş bir bildirim için RenderManifest::fromArray() yöntemini kullanın. Ham kurucu @internal niteliğindedir: yeni isteğe bağlı alanlar varsayılan değerlerle eklenir; böylece oluşturucu ve fromArray() bu alanları çağrı noktalarınızı bozmadan kapsar.

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

Alanlar

Alan	Anlamı
jobId	Çağıran taraf için kararlı mantıksal tanımlayıcı; olaylara ve makbuzlara yansıtılır. İdempotency anahtarına dahil edilmez.
idempotencyKey	Yinelenenleri deterministik olarak ayıklama anahtarı (aşağıya bakın).
input	İşlenecek veri kaynağı: satır içi yük, bir Uniform Resource Identifier (URI) ya da bir veri kümesi referansı ve içerik karması.
template	İşleme ön yüzü ve isteğe bağlı bir şablon tanımlayıcısı.
fonts	Bildirilen yazı tipi kümesi (varsayılan olarak boştur).
locale	Bir BCP-47 dil etiketi (varsayılan olarak en-US).
conformanceProfile	Kararlı bir profil tanımlayıcısı (varsayılan olarak none).
signaturePolicy	Kararlı bir politika tanımlayıcısı (varsayılan olarak none).
target	Çıktı nesnesi anahtarı, biçim ve üzerine yazma politikası.
linearize	Fast-Web-View bayrağı; doğrusallaştırma ile birlikte çalışır.
metadata	Olaylara yansıtılan, anlamı yorumlanmayan skaler key/value eşlemesi.

İdempotency anahtarı

IdempotencyKey::derive() yalnızca bildirimin işlemeyi belirleyen alt kümesini karmalar: şablon, girdinin içerik karması, yazı tipleri, yerel ayar, uyumluluk, imza politikası, linearize bayrağı ve hedef anahtarı. jobId ve metadata alanlarını bilerek dışarıda bırakır; böylece çıktı hedefi de dahil olmak üzere işlemeyi belirleyen girdileri aynı olan iki istek, iş tanımlayıcıları veya izleme meta verileri farklı olsa bile aynı anahtarı paylaşır ve yinelenenler olarak ayıklanabilir. Çağıran ayrıca açık bir anahtar sağlayabilir; anahtarın hangi yolla üretildiğini isDerived() bildirir.

Şema sürümleme

RenderManifest::SCHEMA_VERSION şema sürümünü sabitler (şu anda 1.0). Bir ana sürüm içinde evrim yalnızca eklemeli ilerler: okuyucu, daha yeni bir ikincil şemadan gelen bilinmeyen anahtarları tolere eder, ancak daha yeni bir ana sürümü reddeder. SchemaCompatibility::assertReadable() bunu fromArray() içinde zorunlu kılar; canRead() / isForwardRead() ise uyumluluğu hata fırlatmadan denetlemenizi sağlar.

Bildirim bir readonly veri aktarım nesnesi (DTO) olduğundan ve kurucusu @internal olduğundan, onu oluşturucu veya fromArray() aracılığıyla oluşturun. Yeni alanlar, varsayılan değere sahip kurucu parametreleri olarak eklenir; bu nedenle alan eklemek bu çağrı noktalarını bozmaz.

Doğrulama

RenderManifestValidator::validate() hata fırlatmaz ve sorunların tümünü toplar: ilk sorunda başarısız olmak yerine bulduğu her sorunu döndürür. Güvenli olmayan çıktı anahtarlarını (dizin atlama, mutlak yollar, akış sarmalayıcıları), birden fazla girdi kaynağını, bilinmeyen uyumluluk profili tanımlayıcısını, geçersiz BCP-47 yerel ayarını ve üzerine yazma politikası uyuşmazlığını reddeder. warnings() öneri niteliğinde, engelleyici olmayan notlar döndürür.

use NextPDF\Manifest\RenderManifestValidator;

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

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

Bir bildirimi işleme

SingleDocumentRenderer bir bildirimi deterministik biçimde tek bir Portable Document Format (PDF) belgesine dönüştürür. Yan etkisiz bir işlemdir: baytları ve bu baytların sha-256 özetini döndürür, hiçbir dosya yazmaz; bu nedenle hazırlama ve tam-bir-kez işleme, çağıranın (veya akış işlemcisinin) sorumluluğunda kalır.

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 yüzeyi

Tür	Çeşit	Başlıca üyeler	Kararlılık	Sürümden beri
RenderManifest	readonly DTO	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	kararlı	3.2.0
RenderManifestBuilder	oluşturucu	create(), with*(), linearized(), build()	kararlı	3.2.0
IdempotencyKey	değer nesnesi	of(), derive(), equals(), isDerived()	kararlı	3.2.0
SchemaCompatibility	yardımcı	canRead(), isForwardRead(), assertReadable()	kararlı	3.2.0
RenderManifestValidator	hizmet	validate(), warnings()	kararlı	3.2.0
SingleDocumentRenderer	hizmet	render(): RenderOutcome	kararlı	3.2.0

fromArray(), gerekli bir alan eksik olduğunda veya şema sürümü okunamadığında RenderManifestException fırlatır.