Pro الإصدار

Filter

لمحة سريعة

يوفّر NextPDF\Pro\Filter مساعدَين مُركَّزَين: مُحلِّلًا لقاموس ⁨PDF⁩ ‏/DecodeParms ومرشّحًا عكسيًا لمُتنبِّئ ⁨PNG⁩ المُطبَّق على الدفقات المفكوكة بـ FlateDecode. وهو دعم المُتنبِّئ الذي يستخدمه مُستخرِجا ⁨Pro Diff⁩ و⁨Classifier⁩؛ وهو ليس إطار مرشّحات عامًا.

التوفّر والترخيص

تُشحَن هذه القدرة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بغلاف ترخيص من فئة Pro. النشر الذي يفتقر إلى ذلك الاستحقاق لا يُحمِّل أصناف هذه القدرة. ‏قارن الإصدارات واحصل على ترخيص.

تتوفر أصناف ⁨Filter⁩ متى كان nextpdf/pro مثبَّتًا؛ ولا يحكم هذه الوحدة أي علم قدرة في وقت التشغيل.

التثبيت

composer require nextpdf/pro:^3

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

قد تكون دفقات ⁨PDF⁩ مضغوطة بـ FlateDecode ومعالَجة مسبقًا إضافيًا بمُتنبِّئ لتحسين الضغط. يُعرّف ⁨ISO 32000-2⁩:2020 §7.4.4.4 مُعامِلات المُتنبِّئ (/Predictor، /Columns، /Colors، /BitsPerComponent) وعائلة مُتنبِّئ ⁨PNG⁩ (الوسوم 10–15).

يحلّل DecodeParms شذرة قاموس /DecodeParms إلى كائن قيمة غير قابل للتغيير بافتراضات سليمة (مُتنبِّئ 1، أعمدة 1، ألوان 1، بتات لكل مكوّن 8). ‏isPngPredictor() صحيح للوسوم 10–15.
يطبّق PngPredictor عكسَ أنواع مرشّح ⁨PNG⁩ الخمسة — None وSub وUp وAverage وPaeth — إضافةً إلى Optimum (المُتنبِّئ 15، وسم لكل صف). يتحقّق من المُعامِلات ويثير InvalidArgumentException على القيم خارج النطاق أو على صف مبتور.

تعكس هذه الوحدة مُتنبِّئًا قائمًا عند قراءة دفق. وهي لا تنفّذ المجموعة الكاملة لمرشّحات دفق ⁨PDF⁩ ولا توفّر خطّافات ضبط المرشّح.

لماذا يعمل بهذه الطريقة

تعكس هذه الوحدة مُتنبِّئًا قائمًا بدلًا من تقديم إطار مرشّحات عام. لا يقرأ مُستخرِجا ⁨Pro Diff⁩ و⁨Classifier⁩ إلا ما كتبه مُنتِج بالفعل، لذا يكفي نطاق ضيّق. يتيح ذلك النطاق تقييد كل مُدخَل قبل معالجة أي بايت. ‏DecodeParms::fromDictionary() هو نقطة الاختناق في وقت التحليل: إذ يرفض الأبعاد السالبة أو المفرطة الحجم ويطبّق افتراضات DecodeParms::__construct() حيث يغيب مفتاح. يُعيد PngPredictor التحقق من تلك الحدود في وقت التطبيق، فيثير /DecodeParms معادٍ خطأً مُصنَّفًا بدلًا من تخصيص كبير. يتفرّع المستدعون بناءً على DecodeParms::isPngPredictor()، مُبقين مُتنبِّئ ⁨TIFF⁩ خارج مرشّح عكسي لا يعالج إلا الوسوم 10–15.

خلفية التصميم: الدفقات والمرشّحات.

عقد السلوك

DecodeParms::fromDictionary(string $raw): self — مطابقة أعداد صحيحة متسامحة مع المسافات البيضاء؛ والمفاتيح الغائبة تُبقي افتراضاتها.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — يجب أن يكون المُتنبِّئ 10–15؛ ويجب أن تكون الأعمدة والألوان ≥ 1؛ ويجب أن تكون البتات لكل مكوّن 1 أو 2 أو 4 أو 8 أو 16؛ وصفٌّ أقصر من الخطوة المحسوبة يثير InvalidArgumentException.
الحتمية. المخرَج دالة نقية للمُدخَلات.

سطح الـ ⁨API⁩ العام

النوع	الصنف	الأعضاء الرئيسيون
`NextPDF\Pro\Filter\DecodeParms`	`final readonly class`	`__construct(int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8)`, `static fromDictionary(string $raw): self`, `isPngPredictor(): bool`
`NextPDF\Pro\Filter\PngPredictor`	`final class`	`static inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string`

مثال شيفرة — بداية سريعة

<?php

declare(strict_types=1);

use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

$parms = DecodeParms::fromDictionary('<< /Predictor 15 /Columns 640 /Colors 3 >>');

if ($parms->isPngPredictor()) {
    $raw = PngPredictor::inverse(
        $flateDecodedBytes,
        $parms->columns,
        $parms->colors,
        $parms->bitsPerComponent,
        $parms->predictor,
    );
}

مثال شيفرة — إنتاج

<?php

declare(strict_types=1);

use InvalidArgumentException;
use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

function undoPredictor(string $decoded, string $dictFragment): string
{
    $parms = DecodeParms::fromDictionary($dictFragment);

    if (! $parms->isPngPredictor()) {
        return $decoded; // no predictor, or TIFF predictor — return as-is
    }

    try {
        return PngPredictor::inverse(
            $decoded,
            $parms->columns,
            $parms->colors,
            $parms->bitsPerComponent,
            $parms->predictor,
        );
    } catch (InvalidArgumentException) {
        return $decoded; // malformed predictor metadata — fail safe
    }
}

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

مُتنبِّئ ⁨TIFF⁩ (الوسم 2) مُتعرَّف عليه من قِبل DecodeParms لكنه لا يخضع للترشيح العكسي من قِبل PngPredictor (الذي يقبل 10–15 فقط). على المستدعين التفرّع بناءً على isPngPredictor().
صفُّ مُتنبِّئ أقصر من الخطوة المحسوبة يُرفَض؛ ولا يُبتر بصمت.
تُحسَب خطوة الصف من columns * colors * bitsPerComponent؛ وعدم تطابق /DecodeParms مع تخطيط الدفق الفعلي يُنتج خطأ مُعامِل أو بتر بدلًا من مخرَج تالف.

الأداء

‏PngPredictor::inverse() خطّي بطول الدفق بثابت صغير لكل بايت. تحليل DecodeParms بضع مطابقات تعابير نمطية محدودة. انظر performance_budget.

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

تُتحقَّق نطاقات المُعامِلات قبل أي معالجة بايتات، وصفٌّ مبتور يثير استثناءً بدلًا من القراءة خارج الحدود. على المستدعين الذين يعكسون المُتنبِّئات على دفقات غير موثوقة أن يحدّوا أيضًا الحجم بعد فكّ الضغط في المنبع، كما يفعل مُستخرِجا ⁨Pro Diff⁩ و⁨Classifier.⁩

المطابقة

الادعاء	بند المعيار	الحالة
مُعامِلات `/DecodeParms` وافتراضاتها	ISO 32000-2:2020 §7.4.4.4	مُتحقَّق منه (مجموعة وحدات)
مرشّح مُتنبِّئ ⁨PNG⁩ العكسي، الوسوم 10–15	ISO 32000-2:2020 §7.4.4.4	مُتحقَّق منه (مجموعة وحدات)
إطار مرشّح دفق ⁨PDF⁩ الكامل	—	غير مدعوم (خارج النطاق)

احتياط ⁨Core⁩ / بديله

لا يُعرَض أي مكافئ في ⁨Core⁩ لعكس مُتنبِّئ ⁨PNG.⁩ معالجة الدفق الخاصة بـ ⁨Core⁩ داخلية في المحرّك وليست جزءًا من هذا السطح العام.

ملاحظة حدود ⁨Enterprise⁩

هذا مساعد مُتنبِّئ ضيّق. وهو ليس مرشّحًا تشفيريًا، ولا مُنقّي محتوى، ولا مكوّن إعادة بناء/نزع سلاح للبيانات؛ تلك الشؤون خارج النطاق.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الـ ⁨API⁩ العام المدعوم فقط. مسارات فضاء الأسماء الداخلية، وأصناف المساعدة، وجداول الآليات، وأسماء ملفات دليل التشغيل، وبادئات التذاكر خارج النطاق.