Inspect: PDF-introspectie en preflight

In een oogopslag

De Inspect-module leest een bestaand Portable Document Format (PDF)-bestand en rapporteert wat het bevat: een complexiteitsscore, lettertype- en afbeeldingsaudits, conformiteitshints en risicovlaggen. Een preflight-beleid zet het rapport om in een pass/fail-beslissing, zodat je een document kunt afkeuren voordat het een pijplijn binnenkomt.

Stabiliteit: experimenteel. Introspectie is nog in ontwikkeling. De InspectResult-vorm, de set risicovlaggen en het optionele versnelde inspectiepad kunnen tussen minorversies veranderen. Gebruik het voor diagnostiek en om documenten af te keuren; vertrouw voor langlopende contracten nog niet op de vorm van het resultaat.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Gebruik Inspector als toegangspunt. Het implementeert InspectorInterface en stelt één methode beschikbaar: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. Het werkt alleen-lezen: het ontleedt een PDF en karakteriseert deze; het wijzigt het document niet.

InspectResult is het gestructureerde rapport. Het bevat de complexiteitsscore, audits, hints en een set RiskFlag-waarden. Gebruik hasRisks() / hasRisk(RiskFlag $flag) om op een specifiek risico te vertakken in plaats van vrije tekst te ontleden. ComplexityScore biedt een numerieke score en een band via category(). FontAuditEntry en ImageAuditEntry beschrijven ingesloten bronnen. ComplianceHint markeert waarschijnlijke conformiteitsproblemen. InspectIssue legt een specifieke bevinding vast. InspectDepth bepaalt de inspectiediepte en toSpectrumDepth() vertaalt die diepte naar het versnelde pad wanneer de Spectrum-sidecar beschikbaar is. Inspectie werkt ook zonder de sidecar. De sidecar beïnvloedt alleen de prestaties, niet het contract. InspectResponseParser bouwt een InspectResult op uit een ruwe respons (bijvoorbeeld de respons van het versnelde pad) met een optionele trace-ID.

PreflightPolicy is de beslissingslaag. evaluate(InspectResult $result) past een geconfigureerd beleid toe op een resultaat en retourneert de beleidsuitkomst. De hele module is @since 2.2.0.

API-oppervlak

Type	Belangrijkste leden	Rol
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Alleen-lezen PDF-inspector (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), score- en audit-accessors	Gestructureerd inspectierapport (@since 2.2.0)
ComplexityScore	category()	Numerieke complexiteitsscore + band (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	accessors voor bronnen	Audits van ingesloten bronnen (@since 2.2.0)
ComplianceHint / InspectIssue	accessors voor bevindingen	Conformiteitshints en bevindingen (@since 2.2.0)
InspectDepth (enum)	toSpectrumDepth()	Inspectiediepte → versneld pad (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Pass/fail-preflightbeslissing (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Bouwt een resultaat op uit een ruwe respons (@since 2.2.0)

Voer composer docs:generate-api-php -- --module=Inspect uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snel aan de slag

Bron: examples/34-inspect-layout-boxes.php laat zien hoe je de paginageometrie uitleest. Dit voorbeeld inspecteert het risicoprofiel van een willekeurige 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";
}

Codevoorbeeld — Productie

Controleer een binnenkomende PDF via een preflight-beleid en wijs die af bij elk risico.

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

Randgevallen en valkuilen

• inspect() is alleen-lezen. Het wijzigt of herstelt de invoer nooit; verwacht niet dat het een „gerepareerd” document retourneert.
• hasRisk(RiskFlag) is de nauwkeurige controle. Als je alleen op hasRisks() vertakt, behandel je elk risico op dezelfde manier; meestal wil je een specifieke vlag.
• InspectDepth bepaalt de kosten. Een diepe inspectie van een grote PDF is aanzienlijk trager; gebruik de minst diepe inspectie die je vraag beantwoordt.
• Het door Spectrum versnelde pad verandert de prestaties, niet het resultaatcontract. Programmeer tegen InspectResult, niet tegen de vorm van de versnelde respons.
• PreflightPolicy::evaluate() retourneert de bevindingen; het werpt geen exceptie. Een leeg resultaat is een pass; handel op basis van de retourwaarde.

Prestaties

De inspectiekosten schalen mee met de documentgrootte en de gekozen InspectDepth. Een oppervlakkige inspectie is snel; een diepe audit van een grote PDF kan het budget benaderen. Het Spectrum-pad neemt het zware ontleedwerk over wanneer het beschikbaar is. Het performance_budget van 1500 ms wall / 64 MB piek beschrijft de referentiewerklast. Het reproduceerbaarheidsprofiel is structural: een resultaat kan een trace-ID en timing bevatten. Twee uitvoeringen kunnen in die velden verschillen, terwijl de bevindingen voor dezelfde invoer stabiel blijven.

Beveiligingsnotities

Inspector::inspect() ontleedt niet-vertrouwde PDF-bytes; daar is het voor bedoeld, dus behandel de invoer als vijandig. Voer de inspectie van door gebruikers aangeleverde documenten uit in een begrensde worker en beperk de invoergrootte stroomopwaarts. Een opzettelijk complexe PDF is een denial-of-service-vector, ongeacht de diepte. Het resultaat beschrijft het document, maar saneert het niet; een oordeel „laag risico” is een heuristiek, geen veiligheidsgarantie. Behandel geëxtraheerde strings en metadata als niet-vertrouwd. Zie het dreigingsmodel van de engine in /modules/core/security/.

Conformiteit

Deze module rapporteert conformiteitshints; hij levert niet het gezaghebbende conformiteitsoordeel. ComplianceHint markeert waarschijnlijke problemen heuristisch. Voor PDF/A, PDF/UA en International Organization for Standardization (ISO) 32000-2 komt het gezaghebbende conformiteitsoordeel van de referentievalidators die worden aangestuurd door /modules/core/cli/ en van de oracle- en golden-suites die worden beschreven in /modules/core/conformance/. Beschouw een schoon Inspect-resultaat niet als conformiteitscertificering.

Zie ook

• CLI-module — stuurt de gezaghebbende externe validators aan.
• Conformiteitsoverzicht — het gezaghebbende oordeel en de golden-suites.
• Accelerator-module — het optionele versnelde inspectiepad.
• Beveiligingsmodel van de engine