إصدار شجرة بنية موسومة وفق PDF/UA-2 من محتوى دلالي

لمحة سريعة

تنشئ هذه الوصفة ملف ⁨Portable Document Format/Universal Accessibility 2⁩ ‏(⁨PDF/UA-2⁩) موسومًا، وتستهدف معيار ⁨International Organization for Standardization⁩ ‏(⁨ISO⁩) 14289-2. يُصدر ⁨NextPDF⁩ شجرة بنية منطقية، وتسلسلات محتوى موسوم، ولغة الفهرس، وبيانات تعريف تحديد الهوية على مستوى المستند. تدعم هذه البنية التأليف القابل للوصول، لكن مدقِّقًا مستقلًا هو من يقرر المطابقة. تتبع الوصفة examples/31-pdfua2-tagged.php.

التثبيت

composer require nextpdf/core:^3

ضع مدقِّق ⁨PDF/UA-2⁩ على PATH لإجراء التحقق. تستخدم هذه الوصفة ⁨veraPDF⁩ بنكهة ua2. لا تحتاج إلى حزمة ⁨Pro⁩ أو ⁨Enterprise⁩ لإصدار البنية الموسومة.

نظرة مفاهيمية عامة

يحمل ملف ⁨PDF⁩ الموسوم شجرة بنية منطقية موازية لدفق المحتوى المرئي. تقرأ التقنية المساعِدة هذه الشجرة بدلًا من تخطيط البكسل، لذلك تحدِّد البنية ترتيب القراءة المكشوف. يضع ⁨ISO 14289-2⁩ أربعة متطلبات في هذا السياق. يجب أن يكون المحتوى الحقيقي (غير المُصنَّف كأثر) قابلًا للوصول عبر تلك الشجرة (§8.2.2). ويجب أن تتداخل عناصر البنية بترتيب محدَّد (§8.2.3). كما يجب أن يُحَل كل عنصر إلى فضاء أسماء بنية معروف، إما مباشرةً أو عبر تخطيط الأدوار (§8.2.4). وتُعلَن اللغة الطبيعية للمحتوى على مستوى المستند، ثم تُضبَط لكل عنصر بنية عند اختلافها (§8.4.4).

يُمثِّل ⁨NextPDF⁩ ذلك باستخدام ConformanceMode مُحدَّد النوع. تضبط enableTaggedPdf() القيمة ConformanceMode::PdfUa2، وهذا (أ) يجعل مسار ⁨Hypertext Markup Language⁩ ‏(⁨HTML⁩) يربط TaggedContentEmitter عند بناء المحلِّل، و(ب) يضبط راية الفهرس MarkInfoMarked التي تشير إلى ملف ⁨PDF⁩ موسوم (⁨ISO 32000-2⁩ §14.7)، و(ج) يسجِّل لغة ⁨Best Current Practice 47⁩ ‏(⁨BCP 47⁩) لمدخل الفهرس Lang. يُصدر الكاتب أيضًا مدخل Tabs لكل صفحة، بحيث يتبع ترتيب علامات التبويب ترتيب البنية (⁨ISO 32000-2⁩ §14.8).

لا تنطبق ثوابت ⁨UA-2⁩ الصارمة إلا على ConformanceMode::PdfUa2. وبحكم التصميم، يؤدي إنشاء ConformancePolicy صارم مع أي وضع آخر إلى طرح InvalidConfigException.

واجهة ⁨API⁩

تأتي واجهة ⁨application programming interface⁩ ‏(⁨API⁩) من ⁨PHPDoc.⁩ استخدم نقاط الدخول الرئيسية الآتية:

\NextPDF\Core\Document::createStandalone(): Document
Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static
Document::setLanguage(string $lang): static
\NextPDF\Conformance\ConformancePolicy::strictUa2(): self
\NextPDF\Conformance\ConformanceMode::PdfUa2 (الوضع الذي تضبطه enableTaggedPdf())
Document::beginTag(string $type): static / Document::endTag(): static (وسم يدوي للمحتوى غير المعتمد على ⁨HTML⁩)

نموذج برمجي — بداية سريعة

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Enable tagged mode BEFORE writeHtml(). The HTML pipeline detects the
// mode at parser construction time and wires the tagged-content emitter.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Quarterly Accessibility Report');
$doc->setLanguage('en');
$doc->addPage();

$doc->writeHtml(<<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML);

$doc->save(__DIR__ . '/output/31-pdfua2-tagged.pdf');

echo "Created: output/31-pdfua2-tagged.pdf\n";

نموذج برمجي — إنتاجي

يمكن لهذا البرنامج المكتفي ذاتيًا أن يعمل داخل بيئة التشغيل. في بيئة الإنتاج، أخفِق سريعًا عند وجود وسم لغة مُشوَّه بدلًا من اكتشافه لاحقًا فقط عند تشغيل المدقِّق الخارجي. مرِّر ConformancePolicy::strictUa2() لرفض وسم ⁨BCP 47⁩ غير صالح عند حدود ⁨API⁩، ثم اربط البناء بقرار المدقِّق.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Conformance\ConformancePolicy;
use NextPDF\Core\Document;
use NextPDF\Exception\InvalidConfigException;

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: (__DIR__ . '/accessible.pdf');

try {
    $doc = Document::createStandalone();

    // Strict UA-2: a malformed BCP 47 tag throws here, not silently at
    // write time. strictUa2() also forces the §8.4.4 Lang validation.
    $doc->enableTaggedPdf(lang: 'en-GB', policy: ConformancePolicy::strictUa2());

    $doc->setTitle('Accessible Annual Report 2026');
    $doc->setLanguage('en-GB');
    $doc->addPage();

    $doc->writeHtml(<<<'HTML'
<h1>Annual Report 2026</h1>
<p>Audited results for the financial year ending March 2026.</p>
<h2>Segment performance</h2>
<table>
  <tr><th>Segment</th><th>Revenue</th></tr>
  <tr><td>Cloud</td><td>42.1</td></tr>
  <tr><td>Services</td><td>18.7</td></tr>
</table>
HTML);

    $doc->save($out);
} catch (InvalidConfigException $e) {
    fwrite(STDERR, "Tagged PDF/UA-2 setup rejected: {$e->getMessage()}\n");
    exit(1);
}

// The gate is the checker, not the library.
$exitCode = 0;
$report = [];
exec('verapdf --flavour ua2 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — output is not PDF/UA-2 conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — accessible.pdf carries a conforming UA-2 structure\n";

على مضيف يُبلِّغ فيه verapdf --flavour ua2 عن ملف مطابق، يكون المخرج القياسي المتوقَّع (⁨STDOUT⁩) كما يأتي:

veraPDF PASS — accessible.pdf carries a conforming UA-2 structure

إذا رفضت enableTaggedPdf() وسم اللغة، يخرج البرنامج بقيمة غير صفرية بعد Tagged PDF/UA-2 setup rejected: … على المخرج القياسي للأخطاء (⁨STDERR⁩). وإذا أبلغ المدقِّق عن مشكلة، فإنه يخرج بقيمة غير صفرية بعد veraPDF FAILED — output is not PDF/UA-2 conforming. المدقِّق هو من يصدر القرار: يُصدر ⁨NextPDF⁩ البنية لكنه لا يؤكِّد المطابقة.

الحالات الحدية والمزالق

ترتيب الاستدعاء. إن استدعاء enableTaggedPdf() بعد writeHtml() لا يَسِم المحتوى المكتوب سابقًا بأثر رجعي. فعِّل وضع الوسم أولًا.
بوابة اللغة الصارمة. من دون سياسة، يُسقَط وسم ⁨BCP 47⁩ غير القابل للتحليل بصمت، ولا يظهر إلا وقت التدقيق. مع ConformancePolicy::strictUa2()، يطرح الوسم نفسه InvalidConfigException عند حدود enableTaggedPdf() (⁨ISO 14289-2⁩ §8.4.4 المسار الصارم).
إعادة التفعيل العديمة الأثر. إذا استدعيت enableTaggedPdf() مرتين، يُحدِّث ⁨NextPDF⁩ اللغة دون إعادة بناء شجرة بنية مأهولة.
الوسم اليدوي. للمحتوى غير المعتمد على ⁨HTML⁩، غلِّف العناصر بـ beginTag() / endTag(). تصبح أدوار الحاويات (Table، TR، L، LI) عناصر تجميع بلا محتوى موسوم. وتحصل الأدوار الورقية (P، H1–H6، TD) على معرِّفات محتوى موسوم (⁨MCIDs⁩).
حصرية الوضع. لا يكون ConformancePolicy الصارم صالحًا إلا مع ConformanceMode::PdfUa2. يؤدي الجمع بين رايات ⁨UA-2⁩ الصارمة ووضع ⁨PDF/A⁩ إلى طرح InvalidConfigException. أنشئ مُخرجًا موسومًا بصيغة ⁨PDF/A⁩ عبر تفعيل وضع الوسم وملف تعريف ⁨PDF/A⁩ كلٍّ على حدة.

الأداء

تضيف شجرة البنية شجرة موازية واحدة من القواميس خفيفة الوزن، إضافةً إلى مُعاملي BDC/EMC لكل تشغيلة نص. وفي تقرير نمطي، لا يتجاوز العبء بضع نقاط مئوية من حجم المُخرج، ويبقى ضمن ميزانية 2000 ⁨ms⁩ / 128 ⁨MB⁩ بأريحية. ينطبق ملف تعريف القابلية للتكرار الدلالي لأن المُخرج الموجَّه إلى المدقِّق يُقارَن عبر شجرة الصياغة المجرَّدة البنيوية (⁨AST⁩) إضافةً إلى بيانات التعريف، لا عبر البايتات الخام. راجع قسم المطابقة.

ملاحظات الأمان

إقامة البيانات وإجراءات التخفيف الخاصة بالـ ⁨PII⁩

تحمل شجرة البنية النص نفسه الذي يحمله المحتوى المرئي. إذا احتوى مصدر ⁨HTML⁩ على بيانات شخصية، بما في ذلك المعلومات الشخصية القابلة للتعريف (⁨PII⁩)، فستكون تلك البيانات قابلةً للوصول أيضًا عبر الشجرة وعبر سمتَي ActualText/Alt. طبِّق التنقيح والتقليل نفسيهما قبل التأليف كما تفعل مع المحتوى المرئي. لا يضيف الوسم أي مسار تسريب جديد، لكنه يجعل النص قابلًا للاستخراج برمجيًا بحكم التصميم.

القياس عن بُعد الآمن وتنقية السجلات

تكتب الوصفة سطر تقدُّم ثابتًا فقط إلى ⁨STDOUT.⁩ وتوجِّه ملف ⁨PDF⁩ إلى القناة الجانبية لبيئة التشغيل (NEXTPDF_COOKBOOK_OUTPUT) أو إلى مسار المستدعي. لا يُسجَّل نص المستند أبدًا. أبقِ مُخرج المدقِّق، الذي قد يردِّد أجزاءً من المحتوى، خارج السجلات المشتركة.

نموذج التهديد

ملف ⁨PDF⁩ الموسوم ليس حدًّا للثقة. إذا وثق المستهلك بشجرة البنية للمعالجة الآلية، فلا يزال عليه التحقق من الملف؛ إذ قد يُصدر منتِج معادٍ شجرةً سليمة البنية لكنها مضلِّلة. تعامل مع البنية بوصفها وسيلةً للوصول، لا بوصفها إشارةً للسلامة أو الموثوقية.

السلوك في وضع ⁨FIPS⁩

لا تُجري هذه الوصفة أي عملية تشفيرية. ولا يغيِّر وضع ⁨Federal Information Processing Standards⁩ ‏(⁨FIPS⁩) سلوكها. لا ينطوي الأمر على أي توقيع أو تشفير.

تعيين ⁨PDF/UA-2⁩

متطلب ⁨PDF/UA-2⁩	ما يُصدره ⁨NextPDF⁩	البند
المحتوى الحقيقي موجود في شجرة البنية	`StructTreeRoot` مع `StructElem` لكل كتلة ومحتوى موسوم مرتبط بـ ⁨MCID⁩	⁨ISO 14289-2⁩ §8.2.2
التداخل المحدَّد وترتيب القراءة	عناصر الكتل المُعيَّنة إلى أدوار ⁨grouping/leaf⁩ بترتيب المستند	⁨ISO 14289-2⁩ §8.2.3
فضاء أسماء بنية معروف	أدوار في فضاء أسماء ⁨PDF 2.0⁩؛ ووسوم ⁨HTML⁩ مُعيَّنة الأدوار حيثما لزم الأمر	⁨ISO 14289-2⁩ §8.2.4
لغة المستند والعنصر	الفهرس `Lang` من وسم ⁨BCP 47⁩؛ و`Lang` لكل عنصر عند اختلافها	⁨ISO 14289-2⁩ §8.4.4
المحتوى غير النصي له بديل نصي	`Alt`/`ActualText` محمولان على عناصر بنية ⁨figure/non-text⁩	⁨ISO 14289-2⁩ §8.5.1
علاقات الجداول	أدوار `Table`/`TR`/`TH`/`TD` مع ربط الترويسات	⁨ISO 14289-2⁩ §8.2.5.26
بيانات تعريف تحديد الجزء	تحديد الهوية على مستوى المستند مُجدوَل عند الحفظ	⁨ISO 14289-2⁩ §⁨Intro⁩ (`pdfua2#p17`)

الوسم ← ⁨ISO 32000-2⁩ §14 إحالة مرجعية

يضيف ⁨PDF/UA-2⁩ متطلبات الوصول فوق آلية ⁨PDF⁩ الموسوم في ⁨ISO 32000-2.⁩ يعتمد ⁨NextPDF⁩ هذا التعيين:

إصدار ⁨NextPDF⁩	مرفق ⁨ISO 32000-2⁩ §14	البند
شجرة البنية المنطقية (`StructTreeRoot`)	بنية ⁨PDF⁩ المنطقية الموسومة	§14.7 (`iso32000_2_sec14#x1.x38.p13`)
الفهرس `MarkInfo << /Marked true >>`	علامة ⁨PDF⁩ الموسوم	§14.7 (`iso32000_2_sec14#x1.x40.p3`)
مدخل `Tabs` لكل صفحة يتبع ترتيب البنية	التنقل البنيوي / ترتيب علامات التبويب	§14.8 (`iso32000_2_sec14#x1.x50`)

تعيين ⁨WCAG 2.2⁩

⁨PDF/UA-2⁩ هو التعبير بصيغة ⁨PDF⁩ عن متطلبات البنية التي تنص عليها ⁨Web Content Accessibility Guidelines⁩ ‏(⁨WCAG⁩) 2.2 بصورة مستقلة عن الصيغة. والمواءمة ذات الصلة هي:

معيار نجاح ⁨WCAG 2.2⁩	آلية ⁨PDF/UA-2⁩ التي تنتجها هذه الوصفة
1.3.1 المعلومات والعلاقات (المستوى ⁨A⁩)	تجعل شجرة البنية العناوين والقوائم وعلاقات الجداول قابلةً للتحديد برمجيًا (`wcag_2_2#x2.x3.x3.x1.p3`).
1.3.2 التسلسل ذو المعنى (المستوى ⁨A⁩)	يحدِّد ترتيب البنية ترتيب القراءة بمعزل عن التخطيط المرئي.
3.1.1 لغة الصفحة (المستوى ⁨A⁩)	مدخل الفهرس `Lang` من وسم ⁨BCP 47.⁩
1.1.1 المحتوى غير النصي (المستوى ⁨A⁩)	`Alt`/`ActualText` على عناصر البنية غير النصية (⁨ISO 14289-2⁩ §8.5.1).

يبيِّن هذا التعيين مواضع دعم البنية المُصدَرة لمعايير ⁨WCAG 2.2.⁩ وهو ليس ادعاءً بمطابقة ⁨WCAG.⁩ تغطي مطابقة ⁨WCAG⁩ تجربة المستخدم بأكملها، ويحدِّدها تقييم للوصول، لا المنتِج.

المطابقة

العبارة	المعيار	البند
المحتوى الحقيقي يتطلب بنيةً منطقية.	⁨ISO 14289-2⁩	§8.2.2
تتبع عناصر البنية تداخلًا وترتيب قراءة محدَّدَين.	⁨ISO 14289-2⁩	§8.2.3
يُحَل كل عنصر بنية إلى فضاء أسماء معروف، مباشرةً أو عبر تخطيط الأدوار.	⁨ISO 14289-2⁩	§8.2.4
تُعلَن اللغة الطبيعية على مستوى المستند ومستوى عنصر البنية.	⁨ISO 14289-2⁩	§8.4.4
المحتوى غير النصي يحمل بديلًا نصيًا.	⁨ISO 14289-2⁩	§8.5.1
خلايا الجداول تحمل علاقات ⁨row/header/data.⁩	⁨ISO 14289-2⁩	§8.2.5.26
علامة ⁨PDF⁩ الموسوم هي راية الفهرس `MarkInfoMarked`.	⁨ISO 32000-2⁩	§14.7
تُقرَّر المطابقة مقابل الجزء، ولا يؤكِّدها المنتِج.	⁨ISO 14289-2⁩	§8.14.2

يُصدر ⁨NextPDF⁩ البنية الموسومة التي تدعم التأليف القابل للوصول. الدعم ليس مطابقة. لا تؤكِّد هذه الوصفة مطابقة ⁨PDF/UA-2.⁩ مدقِّق مستقل، مثل ⁨veraPDF⁩، هو من يصدر ذلك القرار. شغِّل المدقِّق قبل أن تعلن أن ملفًا ما مطابق.