Cli: معالِجات الأوامر ومحوّلات أدوات التحقق الخارجية

لمحة سريعة

توفّر وحدة واجهة سطر الأوامر (⁨CLI⁩) واجهة أوامر التشخيص والمطابقة في المحرّك. وهي تتضمّن معالِجات لأوامر ⁨benchmark⁩ و⁨diff⁩ و⁨init⁩ و⁨verify⁩ و⁨capabilities⁩، إلى جانب محوّلات تُغلِّف أدوات التحقق الخارجية لتنسيق المستندات المحمولة (⁨PDF⁩)، بما في ذلك ⁨veraPDF⁩ ونموذج ⁨Arlington⁩ لتنسيق ⁨PDF⁩، ضمن واجهة واحدة. يستطيع أمر verify واحد تشغيل أيّ محوّل.

التثبيت

composer require nextpdf/core:^3

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

يستخدم كل أمر صنف معالِج تُعيد طريقته execute() رمز خروج العملية. يُشغِّل BenchmarkHandler سيناريوهات قياس الأداء. يقارن DiffHandler المستندات. يُنشئ InitHandler هيكل مشروع. يُشغِّل VerifyHandler التحقق من المطابقة. يُبلِّغ CapabilitiesHandler عن الدعم المتاح في وقت التشغيل. CliOutput هو كاتب ⁨stdout/stderr⁩ البسيط الذي تتشاركه المعالِجات، وبذلك يبقى الإخراج قابلًا للاختبار بدلًا من ربطه بالمتغيّرات العامة. يحلّ BinaryFinder مسار أداة خارجية على المضيف (@since 2.5.0).

سطح التحقق هو الحدّ المعماري الرئيسي. AlternateValidatorAdapter هي الواجهة التي تُنفِّذها أداة التحقق الخارجية. تأخذ validate() مسار ملف ⁨PDF⁩ وComplianceFlavour وتُعيد ComplianceValidationResult. وتُبلِّغ isAvailable() عمّا إذا كانت الأداة الداعمة مثبَّتة، بينما تُرجع toolIdentifier() اسمها التعريفي. تُنفِّذ هذه الواجهة VeraPdfCliAdapter، وArlingtonValidatorAdapter، وAsyncValidatorAdapter. لا يعيد المحرّك تنفيذ أدوات التحقق التابعة لجهات خارجية؛ بل يُشغِّل الأدوات المرجعية ويُوحِّد حكمها. تُبلِّغ أداة التحقق غير المثبَّتة isAvailable() === false بدلًا من إفشال التشغيل، فيُسجِّل التحقق الأداة المفقودة صراحةً. المحوّلات هي @since 3.0.0؛ ومعالِجات ⁨Core⁩ هي @since 2.3.0–@since 2.5.0.

سطح واجهة البرمجة (⁨API⁩)

الصنف	الأعضاء الرئيسيون	الدور
`BenchmarkHandler`	`execute(string $format = 'pretty', ?string $scenario = null): int`	يُشغِّل سيناريوهات قياس الأداء (`@since 2.4.0`)
`VerifyHandler`	`execute(): int`	يقود التحقق من المطابقة
`DiffHandler` / `InitHandler`	`execute(): int`	مقارنة المستندات / هيكلة المشروع
`CapabilitiesHandler`	`execute(string $format = 'pretty'): int`	يُبلِّغ عن قدرات وقت التشغيل (`@since 2.3.0`)
`AlternateValidatorAdapter` (واجهة)	`validate()`، `isAvailable()`، `toolIdentifier()`	عقد أداة التحقق الخارجية (`@since 3.0.0`)
`VeraPdfCliAdapter`	يُنفِّذ المحوّل	يُغلِّف واجهة سطر أوامر ⁨veraPDF⁩ ‏(`@since 3.0.0`)
`ArlingtonValidatorAdapter`	يُنفِّذ المحوّل	يُغلِّف نموذج ⁨Arlington⁩ لتنسيق ⁨PDF⁩ ‏(`@since 3.0.0`)
`AsyncValidatorAdapter`	يُنفِّذ المحوّل	غلاف أداة تحقق يدعم العمل غير المتزامن (`@since 3.0.0`)
`CliOutput`	`write()`، `writeln()`، `error()`	كاتب ⁨stdout/stderr⁩ قابل للاختبار (`@since 2.3.0`)
`BinaryFinder`	حلّ مسار الأدوات الخارجية	يحدّد موقع أدوات المضيف (`@since 2.5.0`)

للاطّلاع على جدول ⁨PHPDoc⁩ الكامل، شغِّل composer docs:generate-api-php -- --module=Cli.

عيّنة برمجية — البدء السريع

المصدر: examples/33-validate-conformance.php. حدّد محوّل أداة تحقق، وتحقّق من توفّره قبل الاستخدام:

<?php

declare(strict_types=1);

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

use NextPDF\Cli\VeraPdfCliAdapter;
use NextPDF\Compliance\ComplianceFlavour;

$validator = new VeraPdfCliAdapter(/* binary path / process factory */);

if (!$validator->isAvailable()) {
    fwrite(STDERR, "veraPDF is not installed; conformance verification skipped.\n");
    exit(2);
}

$result = $validator->validate('/srv/out/report.pdf', ComplianceFlavour::PdfA4);
echo $result->isCompliant() ? "PASS\n" : "FAIL\n";

عيّنة برمجية — الإنتاج

شغِّل التحقق عبر أيّ أدوات تحقق متوفّرة. عامِل الأداة الغائبة على أنها فحص متخطًّى، لا فشل.

<?php

declare(strict_types=1);

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

use NextPDF\Cli\AlternateValidatorAdapter;
use NextPDF\Compliance\ComplianceFlavour;
use Psr\Log\LoggerInterface;

final readonly class ConformanceGate
{
    /** @param list<AlternateValidatorAdapter> $validators */
    public function __construct(
        private array $validators,
        private LoggerInterface $logger,
    ) {}

    public function verify(string $pdfPath, ComplianceFlavour $flavour): bool
    {
        $ran = false;

        foreach ($this->validators as $validator) {
            if (!$validator->isAvailable()) {
                $this->logger->info('Validator absent; skipped.', ['tool' => $validator->toolIdentifier()]);
                continue;
            }

            $ran = true;

            if (!$validator->validate($pdfPath, $flavour)->isCompliant()) {
                $this->logger->error('Conformance failed.', ['tool' => $validator->toolIdentifier()]);

                return false;
            }
        }

        // No validator available is not a pass — surface it.
        return $ran;
    }
}

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

تُعيد أداة التحقق غير المتوفّرة isAvailable() === false ولا تطرح استثناءً. “عدم توفّر أيّ أداة تحقق” ليس نجاحًا؛ عالِجه كحالة منفصلة، كما في عيّنة الإنتاج.
تُشغِّل المحوّلات ملفات تنفيذية خارجية. حكمها هو الحكم الموحَّد للأداة الخارجية، وليس إعادة تنفيذ مستقلة. حافِظ على تحديث الأدوات.
تُعيد execute() الخاصة بالمعالِج رمز خروج العملية. يدلّ الرمز غير الصفري على فشل. مرِّره من غلافك بدلًا من تجاهله.
يحلّ BinaryFinder مسار أداة على المضيف. وقد يحلّ مضيف مختلف نسخة مختلفة من الأداة. ثبِّت البيئة للحصول على تحقق قابل لإعادة الإنتاج.
ملف قابلية إعادة الإنتاج هو structural: تتضمّن تقارير التحقق طوابع زمنية ونسخ الأدوات، لذلك تختلف هذه الحقول بين التشغيلات.

الأداء

العبء الإضافي للمعالِج يكاد لا يُذكر. تهيمن عمليات أدوات التحقق الخارجية على التكلفة، وقد تُبطئ المستندات الكبيرة التنفيذ. يتيح لك AsyncValidatorAdapter تداخل ذلك الكُمون. performance_budget البالغ 1500 ⁨ms⁩ زمنًا فعليًا / 64 ⁨MB⁩ ذروةً هو مرجع المحرّك، لا حدٌّ لأداة تحقق خارجية. يملك إخراج قياس الأداء بنية حتمية، لكنه يتضمّن بالضرورة بيانات توقيت.

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

تُطلِق المحوّلات عمليات خارجية لمسار ملف ⁨PDF.⁩ عامِل ملف ⁨PDF⁩ كمُدخَل غير موثوق، وشغِّل التحقق في بيئة مقيَّدة. تُحلِّل أدوات التحقق الخارجية بيانات معادية. تحقّق من أيّ مسار ملف وحوِّله إلى صورته القانونية قبل تمريره إلى معالِج، حتى لا يؤدي اجتياز المسارات إلى ملف غير مقصود. لا تمرِّر مُدخَلات مستخدِم غير منقّاة كوسائط أوامر. تبني المحوّلات وسائط عمليات، لا سلاسل أوامر صدفة. يبقى ملف الإدخال نفسه تحت سيطرة المهاجم. راجِع نموذج تهديدات المحرّك في /modules/core/security/.

المطابقة

لا تقدّم هذه الوحدة أيّ ادّعاء معياري خاص بها بشأن مواصفة ⁨PDF.⁩ بل تُنسِّق التحقق من المطابقة بتفويضه إلى أدوات تحقق مرجعية: ⁨veraPDF⁩ لـ ⁨PDF/A⁩ و⁨PDF/UA⁩، ونموذج ⁨Arlington⁩ لتنسيق ⁨PDF⁩ لقواعد ⁨ISO 32000-2⁩ البنيوية. توفّر الأداة الخارجية حكم المطابقة المرجعي. وتُوحِّد هذه الوحدة ذلك الحكم وتُبلِّغ عنه. يُوصَف التحقق الشامل من المطابقة والخطوط المرجعية الذهبية في /modules/core/conformance/.

انظر أيضًا

وحدة ⁨Inspect⁩ — استبطان برمجي متاح عبر واجهة سطر الأوامر (⁨CLI⁩).
نظرة عامة على المطابقة — نموذج التحقق والمجموعات الذهبية المرجعية.
وحدة ⁨Compliance⁩ — ملفّات ComplianceFlavour التي تفحصها أدوات التحقق.
نموذج أمان المحرّك