Inspect: kiểm tra nội tại và preflight PDF

Tổng quan nhanh

Mô-đun Inspect đọc một tệp Portable Document Format (PDF) hiện có và báo cáo những gì có trong đó: điểm độ phức tạp, các kiểm tra phông chữ và hình ảnh, gợi ý tuân thủ và cờ rủi ro. Chính sách preflight chuyển báo cáo này thành quyết định pass/fail, để bạn có thể chặn tài liệu trước khi nó đi vào pipeline.

Độ ổn định: thử nghiệm. Việc kiểm tra nội tại vẫn đang phát triển. Hình dạng của InspectResult, tập hợp cờ rủi ro và đường dẫn kiểm tra tăng tốc tùy chọn có thể thay đổi giữa các phiên bản phụ. Hãy dùng nó để chẩn đoán và chặn; chưa nên phụ thuộc vào hình dạng kết quả của nó cho các hợp đồng dài hạn.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Dùng Inspector làm điểm vào. Lớp này hiện thực InspectorInterface và cung cấp một phương thức: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. Đây là thao tác chỉ đọc: nó phân tích cú pháp một PDF và mô tả đặc điểm của PDF đó; nó không sửa đổi tài liệu.

InspectResult là báo cáo có cấu trúc. Nó bao gồm điểm độ phức tạp, các kiểm tra, gợi ý và một tập hợp RiskFlag. Hãy dùng hasRisks() / hasRisk(RiskFlag $flag) để rẽ nhánh theo một rủi ro cụ thể thay vì phân tích cú pháp văn bản tự do. ComplexityScore cung cấp điểm số dạng số và dải category(). FontAuditEntry và ImageAuditEntry mô tả các tài nguyên được nhúng. ComplianceHint đánh dấu các vấn đề tuân thủ có khả năng xảy ra. InspectIssue ghi lại một phát hiện cụ thể. InspectDepth đặt độ sâu kiểm tra, còn toSpectrumDepth() ánh xạ độ sâu đó sang đường dẫn tăng tốc khi sidecar Spectrum khả dụng. Việc kiểm tra vẫn chạy được khi không có sidecar. Sidecar chỉ thay đổi hiệu năng, không thay đổi hợp đồng. InspectResponseParser dựng một InspectResult từ phản hồi thô (ví dụ, phản hồi của đường dẫn tăng tốc) cùng trace ID tùy chọn.

PreflightPolicy là lớp ra quyết định. evaluate(InspectResult $result) áp dụng chính sách đã cấu hình lên một kết quả và trả về phán quyết của chính sách đó. Toàn bộ mô-đun là @since 2.2.0.

Bề mặt API

Kiểu	Thành viên chính	Vai trò
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Bộ kiểm tra PDF chỉ đọc (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), các accessor score/audit	Báo cáo kiểm tra có cấu trúc (@since 2.2.0)
ComplexityScore	category()	Điểm độ phức tạp dạng số + dải (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	các accessor tài nguyên	Kiểm tra tài nguyên được nhúng (@since 2.2.0)
ComplianceHint / InspectIssue	các accessor phát hiện	Gợi ý tuân thủ và phát hiện (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	Độ sâu kiểm tra → đường dẫn tăng tốc (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Quyết định preflight pass/fail (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Dựng kết quả từ phản hồi thô (@since 2.2.0)

Chạy composer docs:generate-api-php -- --module=Inspect để tạo bảng PHPDoc đầy đủ.

Mẫu mã — bắt đầu nhanh

Nguồn: examples/34-inspect-layout-boxes.php minh họa cách đọc hình học trang. Ví dụ này kiểm tra hồ sơ rủi ro của một PDF bất kỳ:

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

Mẫu mã — sản xuất

Chặn một PDF đầu vào bằng chính sách preflight và từ chối PDF đó khi có bất kỳ rủi ro nào.

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

Trường hợp biên & điểm cần lưu ý

• inspect() chỉ đọc. Nó không bao giờ sửa đổi hay sửa chữa đầu vào; đừng kỳ vọng nó trả về một tài liệu “đã sửa”.
• hasRisk(RiskFlag) là phép kiểm tra chính xác. Nếu chỉ rẽ nhánh theo hasRisks(), bạn sẽ xử lý mọi rủi ro như nhau; thông thường, bạn cần một cờ cụ thể.
• InspectDepth kiểm soát chi phí. Việc kiểm tra sâu một PDF lớn chậm hơn đáng kể; hãy dùng độ sâu nông nhất vẫn trả lời được câu hỏi của bạn.
• Đường dẫn tăng tốc bằng Spectrum thay đổi hiệu năng, không thay đổi hợp đồng kết quả. Hãy lập trình dựa trên InspectResult, không dựa vào hình dạng phản hồi của đường dẫn tăng tốc.
• PreflightPolicy::evaluate() trả về các phát hiện; nó không ném ngoại lệ. Kết quả rỗng nghĩa là pass; hãy hành động dựa trên giá trị trả về.

Hiệu năng

Chi phí kiểm tra tỉ lệ với kích thước tài liệu và InspectDepth đã chọn. Kiểm tra nông thì nhanh; kiểm tra sâu trên một PDF lớn có thể tiệm cận ngân sách. Đường dẫn Spectrum đảm nhận phần phân tích cú pháp nặng khi khả dụng. performance_budget 1500 ms thời gian thực / 64 MB đỉnh mô tả khối lượng công việc tham chiếu. Hồ sơ khả năng tái lập là structural: kết quả có thể bao gồm trace ID và thời gian. Hai lần chạy có thể khác nhau ở những trường đó, trong khi các phát hiện vẫn ổn định với cùng một đầu vào.

Lưu ý bảo mật

Inspector::inspect() phân tích cú pháp các byte PDF không tin cậy; đó là mục đích của nó, nên hãy coi đầu vào là thù địch. Với tài liệu do người dùng cung cấp, hãy chạy kiểm tra trong worker bị giới hạn và đặt giới hạn kích thước đầu vào ở lớp phía trên. Một PDF được cố tình làm phức tạp là vectơ tấn công từ chối dịch vụ bất kể độ sâu. Kết quả mô tả tài liệu nhưng không làm sạch tài liệu đó; phán quyết “rủi ro thấp” là suy đoán, không phải bảo đảm an toàn. Hãy coi các chuỗi và metadata được trích xuất là không tin cậy. Xem mô hình mối đe dọa của engine tại /modules/core/security/.

Tuân thủ

Mô-đun này báo cáo các gợi ý tuân thủ; nó không cung cấp phán quyết tuân thủ có thẩm quyền. ComplianceHint đánh dấu các vấn đề có khả năng xảy ra theo cách suy đoán. Đối với PDF/A, PDF/UA và International Organization for Standardization (ISO) 32000-2, phán quyết tuân thủ có thẩm quyền đến từ các trình kiểm định tham chiếu được điều khiển bởi /modules/core/cli/, cùng oracle và các bộ golden được mô tả trong /modules/core/conformance/. Đừng xem một kết quả Inspect sạch là chứng nhận tuân thủ.

Xem thêm

• Mô-đun Cli — điều khiển các trình kiểm định bên ngoài có thẩm quyền.
• Tổng quan tuân thủ — phán quyết có thẩm quyền và các bộ golden.
• Mô-đun Accelerator — đường dẫn kiểm tra tăng tốc tùy chọn.
• Mô hình bảo mật của engine