التحقّق من المطابقة: فحص أوّلي داخل العملية مع مرجع خارجي

لمحة سريعة

استخدم هذه الوصفة لتشغيل أدوات التحقّق من المطابقة في ⁨NextPDF⁩، المكتوبة بلغة ⁨PHP⁩ الخالصة والعاملة داخل العملية، بوصفها فحصًا بنيويًا أوّليًا سريعًا، ثم أرسِل قرار المطابقة المرجعي إلى أداة تحقّق مستقلة. الفحوص داخل العملية ضرورية، لكنها ليست كافية: فالنتيجة النظيفة حقيقة بنيوية، وليست حكم مطابقة. تستخدم الوصفة examples/33-validate-conformance.php ومنظومة الاختبار المرافقة لها tests/Cookbook/Php/ValidateConformanceRecipeTest.php.

التثبيت

composer require nextpdf/core:^3

لا تحتاج أدوات التحقّق العاملة داخل العملية إلى أي سلسلة أدوات خارجية. أمّا في خطوة البوّابة المرجعية، فتحتاج إلى أداة تحقّق خارجية متاحة على PATH. يستخدم المثال ⁨veraPDF.⁩ ولا تحتاج إلى حزمة ⁨Pro⁩ أو ⁨Enterprise.⁩

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

يتضمّن ⁨NextPDF⁩ أدوات تحقّق تعمل داخل العملية ضمن \NextPDF\Compliance\Validator. تتحقّق هذه الأدوات من ثوابت معيارية محدّدة من دون بدء أي عملية خارجية:

• PdfRValidator — تشغّل فحوص دفق البايتات وفق ⁨ISO 23504-1⁩ (⁨PDF/R-1⁩) §5/§6: قائمة السماح لترويسة الملف، والكائنات من الجيل 0، وقائمة السماح لعوامل محتوى الصفحة في §6.5.7 (q/Q/cm/Do فقط)، وقائمة السماح لمفاتيح قاموس ⁨Info⁩ في §6.4.3. وتُرجِع قائمة مسطّحة من النوع PdfRValidationFinding[]؛ وتعني القائمة الفارغة أنّ كل فحص مُبوَّب في §6 قد نجح.
• ArlingtonValidator — تشغّل نحو ⁨Arlington⁩ القابل للقراءة آليًا والتابع لرابطة ⁨PDF⁩ في وضع التقرير فقط. وهي لا تحجب البناء أبدًا، وتسجّل بصمة ⁨SHA⁩ للالتزام المثبَّت للنحو على كل نتيجة، حتى يتمكّن مستهلكو التدقيق من المضاهاة مع لقطة معروفة من المصدر الأعلى.

نطاق هذه الفحوص محدود عن قصد. فهي تكشف الانحراف بين عقد الإصدار والمواصفة، لكنها لا تُثبِت مطابقة ⁨ISO⁩ لملمح مثل ⁨PDF/A-4⁩ أو ⁨PDF/UA-2.⁩ أداة تحقّق مستقلة هي مَن يتخذ ذلك القرار، وحكمها هو بوّابة البناء (يجعل ⁨ISO 19005-4⁩ §6.7.3 هذا صريحًا بالنسبة إلى ⁨PDF/A⁩). تُبقي الوصفة هذا الحدّ واضحًا: فهي تشغّل الفحص الأوّلي داخل العملية، ثم تطبع وتشغّل أمر المرجع الخارجي الذي يحسم القرار.

يوضّح المخطّط أدناه البوّابة ذات المرحلتين. وتحكم المسار قاعدة واحدة: حكم المرجع الخارجي وحده هو ما يجوز الإبلاغ عنه بوصفه مطابقة.

Diagram

واجهة ⁨API⁩

تُولَّد واجهة ⁨API⁩ من ⁨PHPDoc.⁩ استخدم نقاط الدخول الرئيسة التالية:

• \NextPDF\Compliance\Validator\PdfRValidator::validate(string $pdfBytes): list<PdfRValidationFinding>
• \NextPDF\Compliance\Validator\PdfRValidationFinding (للقراءة فقط: clause، severity، message)
• \NextPDF\Compliance\Validator\ArlingtonValidator::validateReportOnly(string $pdfPath): list<ArlingtonFinding>
• \NextPDF\Core\Document::output(?string $filename, OutputDestination $dest): string (OutputDestination::String للبايتات الخام)

عيّنة شيفرة — بداية سريعة

<?php

declare(strict_types=1);

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

use NextPDF\Compliance\Validator\PdfRValidator;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Document under conformance review.', newLine: true);

$bytes = $doc->output(dest: OutputDestination::String);

$findings = (new PdfRValidator())->validate($bytes);

// A finding list is a structural fact, not a conformance verdict.
echo $findings === []
    ? "No in-process PDF/R-1 findings (necessary, not sufficient).\n"
    : count($findings) . " in-process finding(s); not a conformance verdict.\n";

عيّنة شيفرة — بيئة الإنتاج

في بيئة الإنتاج، عامِل أداة التحقّق العاملة داخل العملية بوصفها بوّابة منخفضة الكلفة تفشل سريعًا عند الانحراف البنيوي الواضح. ثم شغّل المرجع الخارجي بوصفه قرار المطابقة المرجعي. حكم المرجع وحده هو ما يجوز الإبلاغ عنه بوصفه مطابقة.

examples/33-validate-conformance.php (gate core)

$bytes = $doc->output(dest: OutputDestination::String);
$doc->save($out);

// 1. In-process pre-check — necessary, not sufficient.
$findings = (new PdfRValidator())->validate($bytes);
foreach ($findings as $finding) {
    fwrite(STDERR, sprintf("[%s] §%s — %s\n",
        $finding->severity, $finding->clause, $finding->message));
}

// 2. The authoritative gate — the external validator decides.
$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — not reported conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — the validator reports the file conforming\n";

شغّل المثال باستخدام php examples/33-validate-conformance.php. فهو يبني ملف ⁨PDF⁩ عاديًا ويطبع النتائج المستخرَجة داخل العملية. يُتوقّع أن ينتج عن ملف ⁨PDF⁩ عادي نتائج تخصّ ⁨PDF/R-1⁩؛ وهذه النتيجة هي موضع الفائدة التعليمية. ثم يطبع المثال أمر المرجع الخارجي المرجعي.

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

• ضروري، لكنه غير كافٍ. تعني قائمة نتائج PdfRValidator الفارغة أنّ فحوص §6 المُبوَّبة قد نجحت، لا أكثر. وهي ليست ادّعاء مطابقة لـ ⁨PDF/A-4⁩ أو ⁨PDF/UA-2.⁩ لا تبلّغ عن المطابقة أبدًا اعتمادًا على نتيجة داخل العملية وحدها.
• ملف ⁨PDF⁩ العادي يفشل في ⁨PDF/R-1⁩ بحكم التصميم. ⁨PDF/R-1⁩ ملمح نقطي يقتصر على الصور؛ ومن المشروع أن ينتج عن ملف ⁨PDF⁩ نصّي عادي نتائج تخصّ §6.5.7 و§6.4.3. يُظهِر المثال هذا عن قصد لتوضيح النقطة: الناتج داخل العملية حقيقة بنيوية، لا حكم.
• ⁨Arlington⁩ للتقرير فقط. لا تطلق ArlingtonValidator::validateReportOnly() استثناءً أبدًا ولا تحجب أبدًا. في وضع النحو فقط، تُصدِر نتيجة info واحدة تُثبِت تحميل بصمة ⁨SHA⁩ للنحو المثبَّت؛ وتُرجِع قائمة فارغة حين لا يكون النحو مُجسَّدًا. لا تبنِ عليها بوّابة ⁨pass/fail⁩ — فهي ناتج للمضاهاة المتقاطعة.
• البايتات مقابل الملف. تأخذ PdfRValidator::validate() سلسلة البايتات الخام (OutputDestination::String)؛ أمّا المرجع الخارجي فيحتاج إلى مسار ملف. احفظ الملف باستخدام save() لتنفيذ خطوة المرجع.
• المدخل الفارغ. تمرير سلسلة فارغة أو خالية من الترويسة إلى PdfRValidator::validate() يُرجِع نتيجة خطأ من نوع §6.2.2 بدلًا من إطلاق استثناء. افحص قائمة النتائج؛ ولا تفترض حدوث استثناء.

الأداء

تستخدم أدوات التحقّق العاملة داخل العملية مسحًا بالتعابير النمطية ومسحًا للبايتات بمرور واحد على ملف ⁨PDF.⁩ وهي سريعة وذات استهلاك منخفض للتخصيص في المستندات الاعتيادية، وتبقى ضمن ميزانية 2000 ⁨ms⁩ / 128 ⁨MB.⁩ وعند وجود المرجع الخارجي، يستحوذ على معظم الزمن الفعلي، لكنه يعمل خارج العملية. ينطبق ملمح إعادة الإنتاج الدلالي. تكمن قيمة المثال في سلوك التحقّق القابل للملاحظة فيه، وتتحقّق منظومة الاختبار من ذلك السلوك عبر شجرة بناء جملة مجرّدة (⁨AST⁩) بنيوية إضافةً إلى مقارنة البيانات الوصفية.

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

موضع إقامة البيانات وإجراءات التخفيف الخاصّة بالمعلومات الشخصية

تقرأ أدوات التحقّق بايتات المستند داخل العملية، ولا يغادر العملية شيء. أمّا المرجع الخارجي، فيستقبل الملف. إذا شغّلت أداة تحقّق مستضافة، فإن محتوى المستند يغادر حدودك. بالنسبة إلى المحتوى الحسّاس، فضّل أداة تحقّق ثنائية محلية، أو احجب المعلومات قبل التحقّق.

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

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

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

النتيجة النظيفة داخل العملية ليست مؤشرًا إلى السلامة أو الأصالة. يمكن لمنتِج معادٍ صياغة ملف يجتاز الفحوص المحدودة النطاق داخل العملية لكنه يفشل في أداة التحقّق الكاملة، أو ملف سليم البنية لكنه مضلِّل. عامِل النجاح داخل العملية بوصفه مُرشِّحًا سريعًا، لا بوصفه ثقة أبدًا.

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

لا تنفّذ هذه الوصفة أي عملية تشفير. ولا يغيّر وضع معايير معالجة المعلومات الفيدرالية (⁨FIPS⁩) من سلوكها. لا يحدث أي توقيع أو تشفير أو حَوسبة بصمة لمادّة الثقة.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
يستخدم محتوى صفحة ⁨PDF/R-1⁩ قائمة السماح للعوامل ⁨q/Q/cm/Do⁩ فقط.	⁨ISO 23504-1⁩	§6.5.7
صفحات ⁨PDF/R-1⁩ محتوى نقطيّ يقتصر على الصور.	⁨ISO 23504-1⁩	§6.5.5
يقيّد ⁨PDF/R-1⁩ مفاتيح قاموس معلومات المستند.	⁨ISO 23504-1⁩	§6.4.4
نحو ⁨Arlington⁩ مضاهاة متقاطعة لنموذج كائنات قابل للقراءة آليًا.	⁨Arlington PDF Model⁩	النحو
أداة التحقّق، لا المنتِج، هي مَن تقرّر المطابقة.	⁨ISO 19005-4⁩	§6.7.3

تتحقّق أدوات التحقّق العاملة داخل العملية في ⁨NextPDF⁩ من ثوابت معيارية محدّدة. الدعم ليس مطابقة؛ والتحقّق ليس اعتمادًا. لا تُثبِت النتيجة النظيفة داخل العملية مطابقة ⁨ISO⁩؛ بل تتخذ ذلك القرار أداة تحقّق مستقلة (مثل ⁨veraPDF⁩). استخدم حكمها بوصفه بوّابة البناء.

انظر أيضًا

• وحدة المطابقة
• صفحة المطابقة الرئيسة
• إنتاج مخرجات ⁨PDF/A-4⁩
• إصدار شجرة بنية ⁨PDF/UA-2⁩ موسومة