Pro phiên bản

Bộ lọc

Tổng quan nhanh

NextPDF\Pro\Filter cung cấp hai trợ giúp tập trung: một bộ phân tích cho dictionary /DecodeParms của PDF và một bộ đảo-ngược-bộ-lọc cho predictor PNG được áp dụng lên các stream đã FlateDecode. Đây là phần hỗ trợ predictor được dùng bởi các bộ trích xuất Pro Diff và Classifier; nó không phải là một khung bộ lọc tổng quát.

Tính khả dụng & cấp phép

Năng lực này có trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một envelope giấy phép cấp Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Các lớp Filter có sẵn bất cứ khi nào nextpdf/pro được cài đặt; không có cờ năng lực lúc chạy nào kiểm soát module này.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Các stream PDF có thể được nén FlateDecode và còn được tiền-xử-lý thêm bằng một predictor để cải thiện việc nén. ISO 32000-2:2020 §7.4.4.4 định nghĩa các tham số predictor (/Predictor, /Columns, /Colors, /BitsPerComponent) và họ predictor PNG (các tag 10–15).

DecodeParms phân tích một mảnh dictionary /DecodeParms thành một đối tượng giá trị bất biến với các mặc định hợp lý (predictor 1, columns 1, colors 1, bits-per-component 8). isPngPredictor() là true cho các tag 10–15.
PngPredictor áp dụng nghịch đảo của năm kiểu bộ lọc PNG — None, Sub, Up, Average, Paeth — cộng với Optimum (predictor 15, tag theo từng hàng). Nó kiểm định các tham số và làm phát sinh InvalidArgumentException trên các giá trị ngoài phạm vi hoặc một hàng bị cắt cụt.

Module này đảo ngược một predictor đang tồn tại khi đọc một stream. Nó không triển khai toàn bộ tập các bộ lọc stream PDF và không cung cấp các hook tinh chỉnh bộ lọc.

Vì sao nó hoạt động theo cách này

Module này đảo ngược một predictor đang tồn tại thay vì cung cấp một khung bộ lọc tổng quát. Các bộ trích xuất Pro Diff và Classifier chỉ đọc những gì một bên tạo đã ghi, nên một phạm vi hẹp là đủ. Phạm vi đó cho phép mọi đầu vào được giới hạn trước khi bất kỳ byte nào được xử lý. DecodeParms::fromDictionary() là điểm nghẽn lúc phân tích: nó từ chối hình học âm hoặc quá lớn và áp dụng các mặc định của DecodeParms::__construct() ở nơi một khóa vắng mặt. PngPredictor kiểm tra lại các giới hạn đó lúc áp dụng, nên một /DecodeParms thù địch làm phát sinh một lỗi có kiểu thay vì một cấp phát lớn. Bên gọi rẽ nhánh theo DecodeParms::isPngPredictor(), giữ predictor TIFF ra khỏi một bộ đảo-ngược-bộ-lọc chỉ xử lý các tag 10–15.

Bối cảnh thiết kế: Streams và bộ lọc.

Hợp đồng hành vi

DecodeParms::fromDictionary(string $raw): self — khớp số nguyên có dung thứ khoảng trắng; các khóa vắng mặt giữ nguyên mặc định của chúng.
PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — predictor phải là 10–15; columns và colors phải ≥ 1; bits-per-component phải là 1, 2, 4, 8 hoặc 16; một hàng ngắn hơn stride được tính toán sẽ làm phát sinh InvalidArgumentException.
Tính tất định. Đầu ra là một hàm thuần túy của các đầu vào.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
`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`

Mẫu mã — Khởi đầu nhanh

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

Mẫu mã — Production

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

Trường hợp biên & lưu ý

Predictor TIFF (tag 2) được DecodeParms nhận diện nhưng không được PngPredictor đảo-ngược-bộ-lọc (nó chỉ chấp nhận 10–15). Bên gọi nên rẽ nhánh theo isPngPredictor().
Một hàng predictor ngắn hơn stride được tính toán sẽ bị từ chối; nó không bị cắt cụt một cách âm thầm.
Stride của hàng được tính từ columns * colors * bitsPerComponent; sự không khớp giữa /DecodeParms và bố trí stream thực tế sẽ tạo ra một lỗi tham số hoặc lỗi cắt cụt thay vì đầu ra hỏng.

Hiệu năng

PngPredictor::inverse() là tuyến tính theo độ dài stream với một hằng số mỗi-byte nhỏ. Việc phân tích DecodeParms là một vài phép khớp biểu thức chính quy có giới hạn. Xem performance_budget.

Ghi chú về bảo mật

Phạm vi tham số được kiểm định trước bất kỳ việc xử lý byte nào, và một hàng bị cắt cụt sẽ làm phát sinh lỗi thay vì đọc ngoài giới hạn. Bên gọi đảo ngược các predictor trên các stream không tin cậy cũng nên giới hạn kích thước sau giải nén ở thượng nguồn, như các bộ trích xuất Pro Diff và Classifier làm.

Sự phù hợp tiêu chuẩn

Tuyên bố	Điều khoản tiêu chuẩn	Trạng thái
Các tham số và mặc định `/DecodeParms`	ISO 32000-2:2020 §7.4.4.4	Đã xác minh (bộ kiểm thử đơn vị)
Đảo-ngược-bộ-lọc predictor PNG, các tag 10–15	ISO 32000-2:2020 §7.4.4.4	Đã xác minh (bộ kiểm thử đơn vị)
Khung bộ lọc stream PDF đầy đủ	—	Không hỗ trợ (ngoài phạm vi)

Phương án dự phòng / thay thế trong Core

Không có tương đương trong Core được phơi bày cho việc đảo ngược predictor PNG. Việc xử lý stream của riêng Core là nội bộ của engine và không thuộc về bề mặt công khai này.

Ghi chú ranh giới Enterprise

Đây là một trợ giúp predictor hẹp. Nó không phải là một bộ lọc mật mã, một bộ làm sạch nội dung, hay một thành phần tái dựng/vô hiệu hóa dữ liệu; những mối quan tâm đó nằm ngoài phạm vi.

Ranh giới công bố

Trang này chỉ mô tả hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket nằm ngoài phạm vi.