Inspect: PDF-Introspektion und Preflight

Auf einen Blick

Das Inspect-Modul liest ein vorhandenes PDF und gibt zurück, was es enthält: einen Komplexitäts-Score, Schriftart- und Bild-Audits, Konformitätshinweise und Risikomarkierungen. Eine Preflight-Richtlinie leitet aus diesem Bericht eine pass/fail-Entscheidung ab, sodass Sie ein Dokument absichern können, bevor es in eine Pipeline gelangt.

Stabilität: experimentell. Die Introspektion ist eine noch in Entwicklung befindliche Oberfläche. Die InspectResult-Struktur, der Umfang der Risikomarkierungen und der optionale beschleunigte Inspektionspfad können sich zwischen Minor-Versionen ändern. Verwenden Sie das Modul für Diagnose und Gating; stützen Sie noch keine langlebigen Verträge auf seine Ergebnisstruktur.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Inspector ist der Einstiegspunkt. Er implementiert InspectorInterface und stellt eine Methode bereit: inspect(string $pdfData, InspectConfig $config = new InspectConfig()): InspectResult. Er arbeitet schreibgeschützt: Er parst ein PDF und charakterisiert es, verändert das Dokument aber nicht.

InspectResult ist der strukturierte Bericht. Er enthält den Komplexitäts-Score, die Audits, die Hinweise und eine Menge von RiskFlags. Mit hasRisks() / hasRisk(RiskFlag $flag) kann ein Aufrufer gezielt auf ein bestimmtes Risiko verzweigen, statt Freitext zu parsen. ComplexityScore stellt einen numerischen Score und ein category()-Band bereit. FontAuditEntry und ImageAuditEntry beschreiben eingebettete Ressourcen. ComplianceHint markiert wahrscheinliche Konformitätsprobleme. InspectIssue erfasst einen bestimmten Befund. InspectDepth wählt die Inspektionstiefe, und toSpectrumDepth() bildet sie auf den beschleunigten Pfad ab, wenn das Spectrum-Sidecar verfügbar ist. Die Inspektion läuft auch ohne das Sidecar. Das Sidecar beeinflusst nur die Leistung, nicht den Vertrag. InspectResponseParser erstellt ein InspectResult aus einer Rohantwort (zum Beispiel der Antwort des beschleunigten Pfads) mit einer optionalen Trace-ID.

PreflightPolicy ist die Entscheidungsschicht. evaluate(InspectResult $result) wendet eine konfigurierte Richtlinie auf ein Ergebnis an und gibt das Richtlinienergebnis zurück. Das gesamte Modul ist @since 2.2.0.

API-Oberfläche

Typ	Wichtige Mitglieder	Rolle
Inspector	inspect(string $pdfData, InspectConfig $config): InspectResult	Schreibgeschützter PDF-Inspektor (@since 2.2.0)
InspectResult	hasRisks(), hasRisk(RiskFlag), score/audit-Accessoren	Strukturierter Inspektionsbericht (@since 2.2.0)
ComplexityScore	category()	Numerischer Komplexitäts-Score + Band (@since 2.2.0)
FontAuditEntry / ImageAuditEntry	Ressourcen-Accessoren	Audits eingebetteter Ressourcen (@since 2.2.0)
ComplianceHint / InspectIssue	Befund-Accessoren	Konformitätshinweise und Befunde (@since 2.2.0)
InspectDepth (Enum)	toSpectrumDepth()	Inspektionstiefe → beschleunigter Pfad (@since 2.2.0)
PreflightPolicy	evaluate(InspectResult): array, toArray()	Pass/fail-Preflight-Entscheidung (@since 2.2.0)
InspectResponseParser	parse(array, InspectConfig, ?string $traceId): InspectResult	Erstellt ein Ergebnis aus einer Rohantwort (@since 2.2.0)

Führen Sie composer docs:generate-api-php -- --module=Inspect aus, um die vollständige PHPDoc-Tabelle zu erhalten.

Codebeispiel — Schnellstart

Quelle: examples/34-inspect-layout-boxes.php demonstriert das Auslesen der Seitengeometrie. So inspizieren Sie das Risikoprofil eines beliebigen 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";
}

Codebeispiel — Produktion

Prüfen Sie ein eingehendes PDF mit einer Preflight-Richtlinie und weisen Sie es bei jedem Risiko zurück.

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

Grenzfälle & Fallstricke

• inspect() arbeitet schreibgeschützt. Die Methode verändert oder repariert die Eingabe niemals; erwarten Sie kein „repariertes“ Dokument zurück.
• hasRisk(RiskFlag) ist die präzise Prüfung. Wenn Sie nur auf hasRisks() verzweigen, behandeln Sie jedes Risiko gleich; meist möchten Sie eine bestimmte Markierung prüfen.
• InspectDepth steuert die Kosten. Eine tiefe Inspektion eines großen PDF ist deutlich langsamer; wählen Sie die geringste Inspektionstiefe, die Ihre Frage beantwortet.
• Der durch Spectrum beschleunigte Pfad ändert die Leistung, nicht den Ergebnisvertrag. Richten Sie Ihren Code an InspectResult aus, nicht an der Struktur der beschleunigten Antwort.
• PreflightPolicy::evaluate() gibt die Befunde zurück und wirft keine Ausnahme. Ein leeres Ergebnis bedeutet Bestehen; steuern Sie anhand des Rückgabewerts.

Leistung

Die Inspektionskosten skalieren mit der Dokumentgröße und der gewählten InspectDepth. Eine flache Inspektion ist schnell; ein tiefes Audit eines großen PDF kann das Budget ausschöpfen. Der Spectrum-Pfad lagert rechenintensives Parsen aus, wenn er verfügbar ist. Das performance_budget von 1500 ms Wall / 64 MB Peak gilt für die Referenzarbeitslast. Das Reproduzierbarkeitsprofil ist structural: Ein Ergebnis kann eine Trace-ID und Timingdaten enthalten. Zwei Läufe können sich in diesen Feldern unterscheiden, während die Befunde für dieselbe Eingabe stabil bleiben.

Sicherheitshinweise

Inspector::inspect() parst nicht vertrauenswürdige PDF-Bytes; das ist sein eigentlicher Zweck. Behandeln Sie die Eingabe daher als feindlich. Führen Sie die Inspektion für von Nutzern gelieferte Dokumente in einem eingeschränkten Worker aus und begrenzen Sie die Eingabegröße vorgelagert. Ein absichtlich komplexes PDF ist unabhängig von der gewählten Tiefe ein Denial-of-Service-Vektor. Das Ergebnis beschreibt das Dokument, bereinigt es aber nicht: Ein Urteil „geringes Risiko“ ist eine Heuristik, keine Sicherheitsgarantie. Behandeln Sie extrahierte Zeichenketten und Metadaten als nicht vertrauenswürdig. Siehe das Bedrohungsmodell der Engine unter /modules/core/security/.

Konformität

Dieses Modul meldet Konformitäts-Hinweise; es liefert kein maßgebliches Konformitätsurteil. ComplianceHint markiert wahrscheinliche Probleme heuristisch. Das maßgebliche PDF/A-, PDF/UA- und ISO 32000-2-Konformitätsurteil stammt von den Referenzvalidatoren, die über /modules/core/cli/ ausgeführt werden, sowie von den Oracle- und Golden-Suiten, die in /modules/core/conformance/ beschrieben sind. Behandeln Sie ein sauberes Inspect-Ergebnis nicht als Konformitätszertifizierung.

Siehe auch

• CLI-Modul — führt die maßgeblichen externen Validatoren aus.
• Konformitätsübersicht — das maßgebliche Urteil und die Golden-Suiten.
• Accelerator-Modul — der optionale beschleunigte Inspektionspfad.
• Sicherheitsmodell der Engine