Eine PDF-Datei auf strukturelle Fakten parsen und prüfen

Auf einen Blick

Dieses Recipe liest mit dem Quick-Fallback des Core-Inspectors strukturelle Fakten aus einer PDF-Datei aus. Dazu gehören die Version, die Seitenzahl, das Verschlüsselungs-Flag, das Signatur-Flag, das Anhang-Flag, die Dateigröße und die Risiko-Flags. Quick läuft vollständig in-process, ohne Spectrum-Sidecar und ohne Netzwerk. Verwenden Sie es für eine schnelle Triage, nicht als Validator.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Eine PDF-Datei hält ihre Version im Datei-Header fest (ISO 32000-2 §7.5.2). Der Trailer enthält einen Datei-Identifikator (/ID) aus zwei Byte-Strings (ISO 32000-2 §7.5.5). Ist eine Signatur vorhanden, liegt sie als Signatur-Dictionary vor, dessen Contents DER-codiertes CMS-SignedData enthält (ISO 32000-2 §12.8.1). Der Quick-Fallback leitet die Version, eine Schätzung der Seitenzahl sowie die Präsenz-Flags für Verschlüsselung, Signatur und Anhänge aus einem begrenzten Scan der Dokument-Bytes ab.

API-Oberfläche

Rufen Sie new Inspector() und anschließend ->inspect(string $pdfData, InspectConfig::quick()) auf. Das Ergebnis ist ein InspectResult mit $pdfVersion, $pageCount, $isEncrypted, $hasSigned, $hasAttachments, $fileSizeBytes, $riskFlags und dem Helper hasRisks().

Code-Beispiel — Schnellstart

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Inspect\InspectConfig;
use NextPDF\Inspect\Inspector;

$pdf = file_get_contents(__DIR__ . '/document.pdf');
$result = (new Inspector())->inspect($pdf, InspectConfig::quick());

printf(
    "v%s, %d page(s), encrypted=%s, signed=%s\n",
    $result->pdfVersion ?? '?',
    $result->pageCount,
    $result->isEncrypted ? 'yes' : 'no',
    $result->hasSigned ? 'yes' : 'no',
);

Code-Beispiel — Produktion

Dies ist das eigenständige Programm, das im Harness lauffähig ist. Es spiegelt examples/39-parse-and-inspect-pdf.php wider: Es baut eine kleine, mehrseitige PDF-Datei im Speicher auf, liest ihre strukturellen Fakten mit dem Quick-Fallback aus und routet anhand dieser Fakten (niemals anhand eines Vertrauensurteils). Der Routing-Zweig dient als Beispiel. Binden Sie Ihre eigene Pipeline, Verifier-Queue und Quarantäne ein.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Inspect\InspectConfig;
use NextPDF\Inspect\Inspector;

// A self-contained input so the program runs with no external file.
$doc = Document::createStandalone();
$doc->setTitle('Parse-and-inspect demo');
$doc->setAuthor('NextPDF Cookbook');
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Page one of the parse-and-inspect demonstration.', newLine: true);
$doc->addPage();
$doc->cell(0, 10, 'Page two.', newLine: true);
$pdf = $doc->getPdfData();

$result = (new Inspector())->inspect($pdf, InspectConfig::quick());

echo 'PDF version : ' . ($result->pdfVersion ?? 'unknown') . "\n";
echo 'Pages       : ' . $result->pageCount . "\n";
echo 'Encrypted   : ' . ($result->isEncrypted ? 'yes' : 'no') . "\n";
echo 'Signed      : ' . ($result->hasSigned ? 'yes' : 'no') . "\n";
echo 'Attachments : ' . ($result->hasAttachments ? 'yes' : 'no') . "\n";
echo 'File size   : ' . $result->fileSizeBytes . " bytes\n";
echo 'Risk flags  : ' . ($result->hasRisks() ? count($result->riskFlags) : 0) . "\n";

// Route on structural facts, not trust verdicts. Replace these calls with
// your own pipeline / verifier queue / quarantine.
if ($result->isEncrypted) {
    // $pipeline->decryptThenContinue($pdf);
    echo "Route: decrypt-then-continue\n";
} elseif ($result->hasSigned) {
    // $verifierQueue->enqueue($pdf);          // see the signature-inspect recipe
    echo "Route: enqueue for cryptographic verification\n";
} elseif ($result->hasRisks()) {
    // $quarantine->hold($pdf, $result->riskFlags);
    echo "Route: quarantine (risk flags present)\n";
} else {
    // $pipeline->continue($pdf);
    echo "Route: continue (no risks, unsigned, unencrypted)\n";
}

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script under the
// semantic profile; emit the document to the side-channel.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
file_put_contents($out !== false && $out !== '' ? $out : __DIR__ . '/inspected.pdf', $pdf);

Erwartete STDOUT-Ausgabe (Version und Größe hängen vom Build ab; die Demo-PDF ist unverschlüsselt, unsigniert und enthält keine Risiken):

PDF version : <version>
Pages       : 2
Encrypted   : no
Signed      : no
Attachments : no
File size   : <n> bytes
Risk flags  : 0
Route: continue (no risks, unsigned, unencrypted)

Edge Cases & Stolperfallen

Quick ist Triage, keine Validierung. Es meldet, was vorhanden und was nicht vorhanden ist. Es verifiziert keine Signaturen, entschlüsselt keine Inhalte und sichert keine Konformität zu. Behandeln Sie das Ergebnis als Routing-Eingabe.
Die Seitenzahl ist eine Schätzung. Der Quick-Fallback zählt Seitenobjekt-Marker. Ein absichtlich fehlerhafter Objektgraph kann die Zählung verfälschen. Verwenden Sie die Spectrum-gestützten Tiefen, wenn eine exakte Zählung wichtig ist.
Standard/Full benötigen den Sidecar. new InspectConfig() (Tiefe Standard) und InspectConfig::full() erfordern den Spectrum-Sidecar. Sie werfen INSPECT-SIDECAR-001, wenn er nicht verfügbar ist, und degradieren nicht stillschweigend zu Quick.
Leere Eingabe. Ein leerer String wirft eine Inspect-Exception mit „PDF data must not be empty“.
Geltungsbereich des Verschlüsselungs-Flags. Das Flag spiegelt einen /Encrypt-Eintrag im Trailer wider. Eine markierte Datei wird vom Inspector nicht entschlüsselt.

Performance

Der Quick-Fallback ist ein begrenzter Scan, kein vollständiges Parsen. Er eignet sich für das Vorabrouting großer Mengen eingehender Dateien, bevor eine aufwendigere Verarbeitung folgt.

Sicherheitshinweise

Der Inspector läuft in-process und liest ausschließlich strukturelle Marker. Keine Dokument-Bytes verlassen den Host, und es wird kein Dokumenttext extrahiert. Ein Risiko-Flag, zum Beispiel eingebettetes JavaScript, ist ein beratendes Signal für das Routing. Es sagt nicht aus, ob die Datei sicher oder unsicher ist.

Konformität

Aussage	Spezifikation	Klausel
Der Datei-Header hält die PDF-Version fest.	ISO 32000-2	§7.5.2
Der Trailer-`/ID` ist ein Datei-Identifikator aus zwei Byte-Strings.	ISO 32000-2	§7.5.5
Das `Contents` eines Signatur-Dictionarys enthält DER-codiertes CMS-SignedData.	ISO 32000-2	§12.8.1

Dieses Recipe meldet strukturelle Fakten. Es sichert nicht zu, dass die Datei gültig, sicher oder konform ist.

Kommerzieller Kontext

Die Inspektionstiefen Standard und Full laufen über den Spectrum-Sidecar. Diese Tiefen ergänzen eine umfassendere Objekt-, Schrift- und Bildanalyse. Der hier dokumentierte Quick-Fallback ist Core und offline.