Inspect: introspekcja i preflight plików PDF

W skrócie

Moduł Inspect wczytuje istniejący plik Portable Document Format (PDF) i raportuje jego zawartość: ocenę złożoności, audyty czcionek i obrazów, wskazówki zgodności oraz flagi ryzyka. Polityka preflight zamienia raport w decyzję pass/fail, dzięki czemu dokument można odrzucić, zanim trafi do potoku.

Stabilność: eksperymentalna. Introspekcja nadal się rozwija. Kształt InspectResult, zbiór flag ryzyka oraz opcjonalna przyspieszona ścieżka inspekcji mogą się zmieniać między wersjami pomniejszymi. Używaj modułu do diagnostyki i odrzucania dokumentów; nie opieraj jeszcze długotrwałych kontraktów na kształcie jego wyniku.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Punktem wejścia jest Inspector. Implementuje InspectorInterface i udostępnia jedną metodę: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. Działa tylko do odczytu: parsuje plik PDF i charakteryzuje go; nie modyfikuje dokumentu.

InspectResult to ustrukturyzowany raport. Zawiera ocenę złożoności, audyty, wskazówki oraz zbiór obiektów RiskFlag. Użyj hasRisks() / hasRisk(RiskFlag $flag), aby rozgałęziać kod według konkretnego ryzyka zamiast parsować swobodny tekst. ComplexityScore udostępnia wynik liczbowy oraz kategorię zwracaną przez category(). FontAuditEntry i ImageAuditEntry opisują osadzone zasoby. ComplianceHint oznacza prawdopodobne problemy ze zgodnością. InspectIssue rejestruje konkretne ustalenie. InspectDepth ustawia głębokość inspekcji, a toSpectrumDepth() mapuje tę głębokość na ścieżkę przyspieszoną, gdy dostępny jest moduł pomocniczy Spectrum. Inspekcja działa bez tego modułu. Moduł pomocniczy zmienia wyłącznie wydajność, nie kontrakt. InspectResponseParser buduje obiekt InspectResult z surowej odpowiedzi (na przykład ze ścieżki przyspieszonej) z opcjonalnym identyfikatorem śledzenia.

PreflightPolicy to warstwa decyzyjna. evaluate(InspectResult $result) stosuje skonfigurowaną politykę do wyniku i zwraca rezultat polityki. Cały moduł jest oznaczony jako @since 2.2.0.

Powierzchnia API

Typ	Kluczowe składowe	Rola
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Inspektor plików PDF tylko do odczytu (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), akcesory wyniku/audytu	Ustrukturyzowany raport inspekcji (@since 2.2.0)
ComplexityScore	category()	Liczbowy wynik złożoności + kategoria (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	akcesory zasobów	Audyty osadzonych zasobów (@since 2.2.0)
ComplianceHint / InspectIssue	akcesory ustaleń	Wskazówki zgodności i ustalenia (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	Głębokość inspekcji → ścieżka przyspieszona (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Decyzja preflight typu pass/fail (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Buduje wynik na podstawie surowej odpowiedzi (@since 2.2.0)

Uruchom composer docs:generate-api-php -- --module=Inspect, aby wygenerować pełną tabelę PHPDoc.

Przykład kodu — szybki start

Źródło: examples/34-inspect-layout-boxes.php pokazuje odczyt geometrii strony. Poniższy przykład sprawdza profil ryzyka dowolnego pliku PDF:

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

Przykład kodu — produkcja

Odrzucaj przychodzący plik PDF za pomocą polityki preflight, gdy wystąpi jakiekolwiek ryzyko.

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

Przypadki brzegowe i pułapki

• inspect() działa tylko do odczytu. Nigdy nie modyfikuje ani nie naprawia danych wejściowych; nie oczekuj, że zwróci „naprawiony” dokument.
• hasRisk(RiskFlag) to precyzyjne sprawdzenie. Rozgałęzianie kodu wyłącznie na podstawie hasRisks() traktuje każde ryzyko identycznie; zwykle potrzebna jest konkretna flaga.
• InspectDepth kontroluje koszt. Głęboka inspekcja dużego pliku PDF jest znacznie wolniejsza; używaj najpłytszej głębokości wystarczającej do danego pytania.
• Ścieżka przyspieszona Spectrum zmienia wydajność, a nie kontrakt wyniku. Pisz kod względem InspectResult, a nie względem kształtu odpowiedzi ścieżki przyspieszonej.
• PreflightPolicy::evaluate() zwraca ustalenia; nie zgłasza wyjątku. Pusty wynik oznacza akceptację; reaguj na zwróconą wartość.

Wydajność

Koszt inspekcji skaluje się z rozmiarem dokumentu oraz wybraną głębokością InspectDepth. Płytka inspekcja jest szybka; głęboki audyt dużego pliku PDF może zbliżyć się do budżetu. Ścieżka Spectrum przejmuje kosztowne parsowanie, gdy jest dostępna. performance_budget wynoszący 1500 ms czasu rzeczywistego / 64 MB szczytu opisuje obciążenie referencyjne. Profil odtwarzalności to structural: wynik może zawierać identyfikator śledzenia i pomiar czasu. Dwa uruchomienia mogą różnić się wartościami tych pól, ale ustalenia pozostają stabilne dla tych samych danych wejściowych.

Uwagi dotyczące bezpieczeństwa

Inspector::inspect() parsuje niezaufane bajty PDF; to jego cel, dlatego traktuj dane wejściowe jako wrogie. Uruchamiaj inspekcję dokumentów dostarczonych przez użytkownika w ograniczonym procesie roboczym i ograniczaj rozmiar danych wejściowych na wcześniejszym etapie. Celowo złożony plik PDF jest wektorem ataku typu odmowa usługi niezależnie od głębokości. Wynik opisuje dokument, ale go nie oczyszcza; werdykt „niskie ryzyko” to heurystyka, a nie gwarancja bezpieczeństwa. Traktuj wyodrębnione ciągi znaków i metadane jako niezaufane. Zobacz model zagrożeń silnika w /modules/core/security/.

Zgodność

Ten moduł raportuje wskazówki zgodności; nie wydaje autorytatywnego werdyktu zgodności. ComplianceHint oznacza prawdopodobne problemy wyznaczone heurystycznie. W przypadku PDF/A, PDF/UA oraz International Organization for Standardization (ISO) 32000-2 autorytatywny werdykt zgodności pochodzi z walidatorów referencyjnych sterowanych przez /modules/core/cli/ oraz z zestawów oracle i golden opisanych w /modules/core/conformance/. Nie traktuj samego wyniku Inspect jako certyfikacji zgodności.

Zobacz także

• Moduł CLI — steruje autorytatywnymi zewnętrznymi walidatorami.
• Przegląd zgodności — autorytatywny werdykt i zestawy golden.
• Moduł Accelerator — opcjonalna przyspieszona ścieżka inspekcji.
• Model bezpieczeństwa silnika