Inspect: الفحص الداخلي لملفات PDF والمعاينة المسبقة

لمحة سريعة

تقرأ وحدة ⁨Inspect⁩ ملف ⁨Portable Document Format⁩ (⁨PDF⁩) قائمًا وتعرض ما يحتويه: درجة التعقيد، وعمليات تدقيق للخطوط والصور، وتلميحات المطابقة، وأعلام المخاطر. تحوِّل سياسة المعاينة المسبقة التقرير إلى قرار ⁨pass/fail⁩، لتتمكَّن من التحكُّم في قبول المستند قبل إدخاله إلى مسار المعالجة.

الاستقرار: تجريبي. لا يزال الفحص الداخلي قيد التطوُّر. قد تتغيَّر بنية InspectResult، ومجموعة أعلام المخاطر، ومسار الفحص المُسرَّع الاختياري بين الإصدارات الثانوية. استخدمه للتشخيص والتحكُّم، ولا تعتمد حتى الآن على بنية نتيجته في العقود طويلة الأمد.

التثبيت

composer require nextpdf/core:^3

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

استخدم Inspector بوصفه نقطة الدخول. فهو يُنفِّذ InspectorInterface ويكشف عن دالة واحدة: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. وهو للقراءة فقط: يحلِّل ملف ⁨PDF⁩ ويصِفه، ولا يعدِّل المستند.

InspectResult هو التقرير المُنظَّم. ويتضمَّن درجة التعقيد، وعمليات التدقيق، والتلميحات، ومجموعة من قيم RiskFlag. استخدم hasRisks() / hasRisk(RiskFlag $flag) للتفرُّع بناءً على مخاطرة محدَّدة بدلًا من تحليل نص حر. يكشف ComplexityScore عن درجة عددية وعن نطاق category(). يصِف FontAuditEntry وImageAuditEntry الموارد المُضمَّنة. يشير ComplianceHint إلى مشكلات المطابقة المُحتمَلة. ويُسجِّل InspectIssue ملاحظة محدَّدة. يضبط InspectDepth عمق الفحص، ويُطابِق toSpectrumDepth() ذلك العمق مع المسار المُسرَّع عند توافر مرافِق ⁨Spectrum⁩. يعمل الفحص دون تلك المرافِق. ولا يغيِّر وجودها إلا الأداء، لا العقد. يبني InspectResponseParser كائن InspectResult من استجابة خام (على سبيل المثال، استجابة المسار المُسرَّع) مع معرِّف تتبُّع اختياري.

PreflightPolicy هو طبقة اتخاذ القرار. تطبِّق evaluate(InspectResult $result) سياسة مُهيَّأة على النتيجة وتُعيد ناتج السياسة. الوحدة بأكملها هي @since 2.2.0.

واجهة الـ ⁨API⁩

النوع	الأعضاء الرئيسية	الدور
`Inspector`	`inspect(string $pdfData, InspectConfig $config): InspectResult`	فاحص ⁨PDF⁩ للقراءة فقط (`@since 2.2.0`)
`InspectResult`	`hasRisks()`، و`hasRisk(RiskFlag)`، ودوال وصول ⁨score/audit⁩	تقرير فحص مُنظَّم (`@since 2.2.0`)
`ComplexityScore`	`category()`	درجة تعقيد عددية + نطاق (`@since 2.2.0`)
`FontAuditEntry` / `ImageAuditEntry`	دوال وصول للموارد	عمليات تدقيق للموارد المُضمَّنة (`@since 2.2.0`)
`ComplianceHint` / `InspectIssue`	دوال وصول للملاحظات	تلميحات المطابقة والملاحظات (`@since 2.2.0`)
`InspectDepth` ‏(⁨enum⁩)	`toSpectrumDepth()`	عمق الفحص ← المسار المُسرَّع (`@since 2.2.0`)
`PreflightPolicy`	`evaluate(InspectResult): array`، و`toArray()`	قرار معاينة مسبقة بالنجاح/الإخفاق (`@since 2.2.0`)
`InspectResponseParser`	`parse(array, InspectConfig, ?string $traceId): InspectResult`	يبني نتيجة من استجابة خام (`@since 2.2.0`)

شغِّل composer docs:generate-api-php -- --module=Inspect لتوليد جدول ⁨PHPDoc⁩ كامل.

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

المصدر: يوضِّح examples/34-inspect-layout-boxes.php قراءة هندسة الصفحة. يفحص هذا المثال مخاطر ملف ⁨PDF⁩ عشوائي:

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;

$result = (new Inspector())->inspect(file_get_contents('/srv/in/incoming.pdf'));

if ($result->hasRisks()) {
    echo "Complexity: {$result->complexityScore()->category()}; risks present.\n";
}

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

تحكَّم في قبول ملف ⁨PDF⁩ وارد باستخدام سياسة معاينة مسبقة، وارفضه عند وجود أي مخاطرة.

<?php

declare(strict_types=1);

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

use NextPDF\Inspect\Inspector;
use NextPDF\Inspect\PreflightPolicy;
use Psr\Log\LoggerInterface;

final readonly class IngestPreflight
{
    public function __construct(
        private Inspector $inspector,
        private PreflightPolicy $policy,
        private LoggerInterface $logger,
    ) {}

    public function accept(string $pdfData): bool
    {
        $result = $this->inspector->inspect($pdfData);
        $verdict = $this->policy->evaluate($result);

        if ($verdict !== []) {
            $this->logger->warning('PDF rejected at preflight.', ['findings' => $verdict]);

            return false;
        }

        return true;
    }
}

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

inspect() للقراءة فقط. فهي لا تعدِّل المُدخَل ولا تصلحه أبدًا؛ ولا تتوقَّع منها أن تُعيد مستندًا “مُصلَحًا”.
hasRisk(RiskFlag) هو فحص المخاطرة المحدَّدة. التفرُّع بناءً على hasRisks() وحده يعامل كل مخاطرة بالطريقة نفسها؛ وعادةً ما تحتاج إلى علم بعينه.
InspectDepth يتحكَّم في التكلفة. الفحص العميق لملف ⁨PDF⁩ كبير أبطأ بكثير؛ فاستخدم أقل عمق يجيب عن سؤالك.
يغيِّر المسار المُسرَّع بواسطة ⁨Spectrum⁩ الأداء، لا عقد النتيجة. اكتب الشِّفرة اعتمادًا على InspectResult، لا على بنية الاستجابة المُسرَّعة.
تُعيد PreflightPolicy::evaluate() الملاحظات؛ وهي لا تطرح استثناءً. النتيجة الفارغة تعني نجاحًا؛ فتصرَّف وفق القيمة المُعادة.

الأداء

تتناسب تكلفة الفحص مع حجم المستند ومع InspectDepth المختار. الفحص السطحي سريع؛ أما التدقيق العميق لملف ⁨PDF⁩ كبير فقد يقترب من الميزانية. يتولَّى مسار ⁨Spectrum⁩ التحليل الثقيل عند توافره. يصِف performance_budget البالغ 1500 ⁨ms⁩ زمنًا جداريًا / 64 ⁨MB⁩ كذروة لعبء العمل المرجعي. ملف تعريف قابلية التكرار هو structural: قد تتضمَّن النتيجة معرِّف تتبُّع وتوقيتًا. قد يختلف تشغيلان في تلك الحقول، بينما تبقى الملاحظات ثابتة للمُدخَل نفسه.

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

تحلِّل Inspector::inspect() بايتات ⁨PDF⁩ غير موثوقة؛ وهذا هو الغرض منها، لذا عامِل المُدخَل بوصفه معاديًا. شغِّل الفحص في عامل مُقيَّد للمستندات المُقدَّمة من المستخدم، وقيِّد حجم المُدخَل عند المصدر. ملف ⁨PDF⁩ المُعقَّد عمدًا متجِّه لحجب الخدمة بصرف النظر عن العمق. تصِف النتيجة المستند لكنها لا تُطهِّره؛ وحُكم “مخاطرة منخفضة” استدلال، لا ضمان أمان. عامِل السلاسل والبيانات الوصفية المُستخرَجة بوصفها غير موثوقة. راجِع نموذج تهديد المحرِّك في /modules/core/security/.

المطابقة

تُبلِّغ هذه الوحدة عن تلميحات مطابقة؛ وهي لا تقدِّم حُكمًا موثوقًا بالمطابقة. يشير ComplianceHint إلى المشكلات المُحتمَلة على نحو استدلالي. بالنسبة إلى ⁨PDF/A⁩ و⁨PDF/UA⁩ و⁨ISO 32000-2⁩ الصادر عن ⁨International Organization for Standardization⁩ (⁨ISO⁩)، يأتي حُكم المطابقة الموثوق من أدوات التحقُّق المرجعية التي يقودها /modules/core/cli/ ومن مجموعات الأوراكل والمجموعات الذهبية الموصوفة في /modules/core/conformance/. لا تعامل نتيجة ⁨Inspect⁩ النظيفة بوصفها شهادة مطابقة.

انظر أيضًا

وحدة ⁨Cli⁩ — تدير أدوات التحقُّق الخارجية الموثوقة.
نظرة عامة على المطابقة — الحُكم الموثوق والمجموعات الذهبية.
وحدة ⁨Accelerator⁩ — مسار الفحص المُسرَّع الاختياري.
نموذج أمان المحرِّك