Pro รุ่น

ตัวกรอง

ภาพรวมโดยสังเขป

NextPDF\Pro\Filter มีตัวช่วยที่เน้นเฉพาะสองตัว ได้แก่ ตัวแจงพจนานุกรม /DecodeParms ของ PDF และตัวกรองย้อนกลับสำหรับตัวทำนาย PNG ที่ใช้กับสตรีมที่ FlateDecode แล้ว นี่คือการรองรับตัวทำนายที่ตัวสกัด Diff และ Classifier ของ Pro ใช้ ไม่ใช่กรอบงานตัวกรองทั่วไป

การมีให้ใช้และการให้สิทธิ์ใช้งาน

ความสามารถนี้มาพร้อมกับ 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 (tags 10–15)

DecodeParms แจงชิ้นส่วนพจนานุกรม /DecodeParms ให้เป็นออบเจ็กต์ค่าที่ไม่เปลี่ยนแปลงพร้อมค่าเริ่มต้นที่สมเหตุสมผล (predictor 1, columns 1, colors 1, bits-per-component 8) isPngPredictor() เป็นจริงสำหรับ tags 10–15
PngPredictor ใช้ส่วนผกผันของตัวกรอง PNG ห้าชนิด ได้แก่ None, Sub, Up, Average, Paeth บวก Optimum (predictor 15, tag ต่อแถว) โดยตรวจสอบพารามิเตอร์และทำให้เกิด InvalidArgumentException เมื่อค่าอยู่นอกช่วงหรือแถวถูกตัดทอน

โมดูลนี้ย้อนกลับตัวทำนายที่ มีอยู่เดิม เมื่ออ่านสตรีม โดยไม่นำชุดตัวกรองสตรีม PDF แบบเต็มไปใช้และไม่มี hook สำหรับปรับแต่งตัวกรอง

เหตุใดจึงทำงานเช่นนี้

โมดูลนี้ย้อนกลับตัวทำนายที่ มีอยู่เดิม แทนที่จะเสนอกรอบงานตัวกรองทั่วไป ตัวสกัด Diff และ Classifier ของ Pro อ่านเฉพาะสิ่งที่ผู้ผลิตเขียนไว้แล้วเท่านั้น ขอบเขตที่แคบจึงเพียงพอ ขอบเขตนั้นทำให้ทุกอินพุตถูกกำหนดขอบเขตก่อนที่จะมีการประมวลผลไบต์ใด ๆ DecodeParms::fromDictionary() คือจุดคอขวดในเวลาแจง โดยปฏิเสธรูปทรงที่เป็นค่าลบหรือใหญ่เกินไปและใช้ค่าเริ่มต้นของ DecodeParms::__construct() เมื่อคีย์ขาดหายไป PngPredictor ตรวจสอบขอบเขตเหล่านั้นซ้ำในเวลาที่ใช้งาน ดังนั้น /DecodeParms ที่เป็นอันตรายจะทำให้เกิดข้อผิดพลาดแบบมีชนิดแทนการจัดสรรหน่วยความจำขนาดใหญ่ ผู้เรียกแยกสาขาบน DecodeParms::isPngPredictor() เพื่อกันตัวทำนาย TIFF ออกจากตัวกรองย้อนกลับที่จัดการเฉพาะ tags 10–15

ที่มาของการออกแบบ: สตรีมและตัวกรอง

สัญญาพฤติกรรม

DecodeParms::fromDictionary(string $raw): self การจับคู่จำนวนเต็มที่ทนต่อช่องว่าง คีย์ที่ขาดหายไปจะคงค่าเริ่มต้นไว้
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string predictor ต้องอยู่ที่ 10–15 columns และ colors ต้อง ≥ 1 bits-per-component ต้องเป็น 1, 2, 4, 8 หรือ 16 แถวที่สั้นกว่า stride ที่คำนวณได้จะทำให้เกิด InvalidArgumentException
ความแน่นอน เอาต์พุตเป็นฟังก์ชันบริสุทธิ์ของอินพุต

พื้นผิว API สาธารณะ

Type	Kind	Key members
`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 (tag 2) ถูกรู้จักโดย DecodeParms แต่ ไม่ ถูกกรองย้อนกลับโดย PngPredictor (ซึ่งรับเฉพาะ 10–15) ผู้เรียกควรแยกสาขาบน isPngPredictor()
แถวตัวทำนายที่สั้นกว่า stride ที่คำนวณได้จะถูกปฏิเสธ โดยไม่ถูกตัดทอนอย่างเงียบ ๆ
stride ของแถวคำนวณจาก columns * colors * bitsPerComponent /DecodeParms ที่ไม่ตรงกับเลย์เอาต์สตรีมจริงจะให้ข้อผิดพลาดเรื่องพารามิเตอร์หรือการตัดทอนแทนที่จะเป็นเอาต์พุตที่เสียหาย

ประสิทธิภาพ

PngPredictor::inverse() เป็นเชิงเส้นตามความยาวสตรีมพร้อมค่าคงที่ต่อไบต์ขนาดเล็ก การแจง DecodeParms เป็นการจับคู่นิพจน์ปกติที่มีขอบเขตไม่กี่ครั้ง ดู performance_budget

บันทึกด้านความปลอดภัย

ช่วงพารามิเตอร์ถูกตรวจสอบก่อนการประมวลผลไบต์ใด ๆ และแถวที่ถูกตัดทอนจะทำให้เกิดข้อยกเว้นแทนที่จะอ่านออกนอกขอบเขต ผู้เรียกที่ย้อนกลับตัวทำนายบนสตรีมที่ไม่น่าเชื่อถือควรกำหนดขอบเขตขนาดที่คลายการบีบอัดที่ต้นทางด้วย เช่นเดียวกับที่ตัวสกัด Diff และ Classifier ของ Pro ทำ

ความสอดคล้องกับมาตรฐาน

Claim	Spec clause	Status
`/DecodeParms` parameters and defaults	ISO 32000-2:2020 §7.4.4.4	Verified (unit suite)
PNG predictor reverse-filter, tags 10–15	ISO 32000-2:2020 §7.4.4.4	Verified (unit suite)
Full PDF stream-filter framework	—	Not supported (out of scope)

ทางเลือก / ทางสำรองของ Core

ไม่มีสิ่งเทียบเท่าใน Core ที่เปิดเผยสำหรับการย้อนกลับตัวทำนาย PNG การจัดการสตรีมของ Core เองเป็นเรื่องภายในของเอนจินและไม่ได้เป็นส่วนหนึ่งของพื้นผิวสาธารณะนี้

บันทึกขอบเขตของ Enterprise

นี่คือตัวช่วยตัวทำนายแบบแคบ โดยไม่ใช่ตัวกรองการเข้ารหัสลับ ตัวทำความสะอาดเนื้อหา หรือคอมโพเนนต์การสร้างใหม่/ปลดอาวุธข้อมูล เรื่องเหล่านั้นอยู่นอกขอบเขต

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต