Pro edisi

Filter

Sekilas pandang

NextPDF\Pro\Filter menyediakan dua helper terfokus: sebuah parser untuk dictionary PDF /DecodeParms dan reverse-filter untuk predictor PNG yang diterapkan pada stream FlateDecoded. Ini adalah dukungan predictor yang dipakai ekstraktor Diff dan Classifier Pro; ini bukan kerangka filter umum.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan amplop lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Kelas Filter tersedia setiap kali nextpdf/pro terpasang; tidak ada flag kapabilitas runtime yang menggerbangi modul ini.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Stream PDF dapat terkompresi FlateDecode dan tambahan diprapemroses dengan predictor untuk memperbaiki kompresi. ISO 32000-2:2020 §7.4.4.4 mendefinisikan parameter predictor (/Predictor, /Columns, /Colors, /BitsPerComponent) dan keluarga predictor PNG (tag 10–15).

DecodeParms mengurai fragmen dictionary /DecodeParms menjadi objek nilai imutabel dengan default yang masuk akal (predictor 1, columns 1, colors 1, bits-per-component 8). isPngPredictor() bernilai true untuk tag 10–15.
PngPredictor menerapkan invers dari lima tipe filter PNG — None, Sub, Up, Average, Paeth — ditambah Optimum (predictor 15, tag per-baris). Ia memvalidasi parameter dan memunculkan InvalidArgumentException pada nilai di luar rentang atau baris yang terpotong.

Modul ini membalikkan predictor yang sudah ada saat membaca stream. Ia tidak mengimplementasikan himpunan lengkap filter stream PDF dan ia tidak menyediakan hook penyetelan-filter.

Mengapa cara kerjanya seperti ini

Modul ini membalikkan predictor yang sudah ada alih-alih menawarkan kerangka filter umum. Ekstraktor Diff dan Classifier Pro hanya membaca apa yang sudah ditulis produser, jadi cakupan yang sempit sudah cukup. Cakupan itu membuat setiap input dapat dibatasi sebelum satu byte pun diproses. DecodeParms::fromDictionary() adalah titik-cekik saat-parse: ia menolak geometri negatif atau berlebihan dan menerapkan default DecodeParms::__construct() di tempat sebuah kunci absen. PngPredictor memeriksa ulang batas-batas itu saat-apply, sehingga /DecodeParms yang berbahaya memunculkan error bertipe alih-alih alokasi besar. Pemanggil bercabang pada DecodeParms::isPngPredictor(), menjaga predictor TIFF tetap di luar reverse filter yang hanya menangani tag 10–15.

Latar desain: Streams and filters.

Kontrak perilaku

DecodeParms::fromDictionary(string $raw): self — pencocokan integer yang toleran terhadap whitespace; kunci yang absen mempertahankan defaultnya.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — predictor harus 10–15; columns dan colors harus ≥ 1; bits-per-component harus 1, 2, 4, 8, atau 16; baris yang lebih pendek dari stride yang dihitung memunculkan InvalidArgumentException.
Determinisme. Keluaran adalah fungsi murni dari input.

Permukaan API publik

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`

Contoh kode — Mulai cepat

<?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,
    );
}

Contoh kode — Produksi

<?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
    }
}

Kasus tepi & jebakan

Predictor TIFF (tag 2) dikenali oleh DecodeParms tetapi tidak di-reverse-filter oleh PngPredictor (yang hanya menerima 10–15). Pemanggil sebaiknya bercabang pada isPngPredictor().
Baris predictor yang lebih pendek dari stride yang dihitung ditolak; ia tidak dipotong secara diam-diam.
Stride baris dihitung dari columns * colors * bitsPerComponent; /DecodeParms yang tidak cocok dengan tata letak stream sebenarnya menghasilkan error parameter atau pemotongan alih-alih keluaran yang rusak.

Performa

PngPredictor::inverse() bersifat linear terhadap panjang stream dengan konstanta per-byte yang kecil. Penguraian DecodeParms adalah beberapa pencocokan regular-expression terbatas. Lihat performance_budget.

Catatan keamanan

Rentang parameter divalidasi sebelum pemrosesan byte apa pun, dan baris yang terpotong memunculkan eksepsi alih-alih membaca di luar batas. Pemanggil yang membalikkan predictor pada stream yang tidak tepercaya juga sebaiknya membatasi ukuran terdekompresi di hulu, sebagaimana dilakukan ekstraktor Diff dan Classifier Pro.

Konformansi

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)

Fallback / alternatif Core

Tidak ada padanan Core yang diekspos untuk pembalikan PNG-predictor. Penanganan stream Core sendiri bersifat internal terhadap mesin dan bukan bagian dari permukaan publik ini.

Catatan batas Enterprise

Ini adalah helper predictor yang sempit. Ia bukan filter kriptografi, pembersih konten, atau komponen rekonstruksi-data/disarm; urusan tersebut berada di luar cakupan.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.