بيان العرض: طلب عرض قابل للنقل

نظرة سريعة

بيان العرض هو الوصف القابل للنقل لـ ما يجب عرضه: المُدخَل، والقالب، والخطوط، واللغة المحلية، وملف تعريف المطابقة، وسياسة التوقيع، وهدف المُخرَج، وعلامة العرض السريع على الويب (⁨Fast-Web-View⁩). تُنشئ كل وسيلة نقل وتقدّم RenderManifest نفسه، سواء أكانت واجهة سطر أوامر (⁨CLI⁩)، أم تكاملًا مع إطار عمل، أم واجهة برمجة تطبيقات (⁨API⁩) لتطبيق برمجيات كخدمة (⁨SaaS⁩)، أم موصِّل دفق مستقبلي. العقد حتمي: ينتج عن تسلسل بيانَيْن متساويين ترميز كائنات ⁨JavaScript⁩ (⁨JSON⁩) متطابق على مستوى البايتات، ويحمل كل بيان مفتاح خمول مشتقًّا لتتمكن الأنظمة اللاحقة من التعرّف على عملية العرض نفسها وإزالة تكرارها.

البيان عقد من عقود ⁨Core.⁩ فهو يُعرِّف المخطط؛ أما تنفيذ الطلب فتتولاه المحرّك ومعالج الدفق في النسخة المدفوعة.

التثبيت

composer require nextpdf/core:^3

إنشاء بيان

استخدم المُنشئ بوصفه مسار البناء المستقر، أو استخدم RenderManifest::fromArray() لبيان أُزيل تسلسله. المُنشئ الخام هو @internal: تُضاف الحقول الاختيارية الجديدة بقيم افتراضية، فيستوعبها المُنشئ وfromArray() دون كسر مواضع الاستدعاء لديك.

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

الحقول

الحقل	المعنى
jobId	مُعرِّف منطقي مستقر بالنسبة إلى المُستدعي، ويُكرَّر في الأحداث والإيصالات. مُستبعَد من مفتاح الخمول.
idempotencyKey	مفتاح إزالة تكرار حتمي (انظر أدناه).
input	مصدر بيانات العرض: حمولة مضمَّنة، أو مُعرِّف مورد موحَّد (⁨URI⁩)، أو مرجع لمجموعة بيانات مع تجزئة المحتوى.
template	الواجهة الأمامية للعرض ومُعرِّف قالب اختياري.
fonts	مجموعة الخطوط المُعلَنة (فارغة افتراضيًّا).
locale	وسم لغة وفق ⁨BCP-47⁩ (en-US افتراضيًّا).
conformanceProfile	مُعرِّف ملف تعريف مستقر (none افتراضيًّا).
signaturePolicy	مُعرِّف سياسة مستقر (none افتراضيًّا).
target	مفتاح كائن المُخرَج، والتنسيق، وسياسة الكتابة فوق الملفات الموجودة.
linearize	علامة العرض السريع على الويب (⁨Fast-Web-View⁩)؛ تتكامل مع الجعل خطيًّا.
metadata	خريطة قيم عددية مُعتمة بصيغة ⁨key/value⁩ تُكرَّر في الأحداث.

مفتاح الخمول

تُجزِّئ IdempotencyKey::derive() المجموعة الفرعية المُحدِّدة للعرض فقط من البيان: القالب، وتجزئة محتوى المُدخَل، والخطوط، واللغة المحلية، والمطابقة، وسياسة التوقيع، وعلامة الجعل خطيًّا، ومفتاح الهدف. وتستبعد عمدًا jobId وmetadata، لذلك يتشارك طلبان لهما مُدخَلات مُحدِّدة للعرض متطابقة، بما في ذلك هدف المُخرَج، المفتاح نفسه، ويمكن إزالة تكرارهما حتى عندما تختلف مُعرِّفات مهامهما أو بيانات التتبّع الوصفية. يمكن للمُستدعي أيضًا توفير مفتاح صريح؛ وتُبلِّغ isDerived() عن المسار الذي أنتجه.

إصدارات المخطط

تُثبِّت RenderManifest::SCHEMA_VERSION إصدار المخطط (وهو حاليًّا 1.0). داخل الإصدار الرئيسي الواحد، يكون التطوّر بالإضافة فقط: يتحمّل القارئ المفاتيح غير المعروفة الواردة من مخطط فرعي أحدث، لكنه يرفض أي إصدار رئيسي أحدث. تفرض SchemaCompatibility::assertReadable() ذلك داخل fromArray()، وتتيح لك canRead() / isForwardRead() اختبار التوافق دون طرح استثناء.

بما أن البيان كائن نقل بيانات (⁨DTO⁩) من نوع readonly ومُنشئه @internal، فابنِه عبر المُنشئ أو fromArray(). تُضاف الحقول الجديدة بوصفها مُعاملات مُنشئ ذات قيم افتراضية، فلا تؤدي إضافة حقل إلى كسر مواضع الاستدعاء هذه.

التحقق

RenderManifestValidator::validate() لا تطرح استثناءات، بل تجمع كل الأخطاء: فهي تُرجِع كل مشكلة تجدها بدلًا من الفشل عند أول مشكلة. وترفض مفاتيح المُخرَج غير الآمنة (التنقّل عبر المسارات، والمسارات المطلقة، ومُغلِّفات الدفق)، ووجود أكثر من مصدر مُدخَل واحد، ومُعرِّف ملف تعريف مطابقة غير معروف، ولغة محلية غير صالحة وفق ⁨BCP-47⁩، وعدم تطابق في سياسة الكتابة فوق الملفات الموجودة. تُرجِع warnings() ملاحظات إرشادية غير حاجبة.

use NextPDF\Manifest\RenderManifestValidator;

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

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

عرض بيان

يحوّل SingleDocumentRenderer بيانًا واحدًا إلى مستند واحد بتنسيق المستندات المحمول (⁨PDF⁩) على نحو حتمي. وهو دالة خالصة: يُرجِع البايتات مع تجزئتها بخوارزمية ⁨sha-256⁩ ولا يكتب أي ملف، فتظل التهيئة والإيداع مرة واحدة بالضبط من مسؤولية المُستدعي (أو معالج الدفق).

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⁩) للقراءة فقط	toArray(), toJson(), fromArray(), canonicalDigestInput(), SCHEMA_VERSION	مستقر	3.2.0
RenderManifestBuilder	مُنشئ	create(), with*(), linearized(), build()	مستقر	3.2.0
IdempotencyKey	كائن قيمة	of(), derive(), equals(), isDerived()	مستقر	3.2.0
SchemaCompatibility	مساعد	canRead(), isForwardRead(), assertReadable()	مستقر	3.2.0
RenderManifestValidator	خدمة	validate(), warnings()	مستقر	3.2.0
SingleDocumentRenderer	خدمة	render(): RenderOutcome	مستقر	3.2.0

تطرح fromArray() الاستثناء RenderManifestException عندما يكون حقل مطلوب مفقودًا أو عند تعذّر قراءة إصدار المخطط.