Een PDF-bestand parseren en inspecteren op structurele feiten

In een oogopslag

Dit recept gebruikt de Quick-fallback van de Core-inspector om structurele feiten uit een Portable Document Format-bestand (PDF) te lezen. Je krijgt de versie, het aantal pagina’s, de versleutelingsvlag, de handtekeningvlag, de bijlagevlag, de bestandsgrootte en de risicovlaggen. Quick draait volledig binnen het proces, zonder Spectrum-sidecar en zonder netwerktoegang. Gebruik deze modus voor snelle triage, niet als validator.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Een PDF-bestand legt zijn versie vast in de bestandsheader (ISO 32000-2 §7.5.2). De trailer bevat een bestands-id (/ID) als twee byte strings (ISO 32000-2 §7.5.5). Wanneer er een handtekening aanwezig is, slaat een handtekeningwoordenboek Distinguished Encoding Rules (DER)-gecodeerde Cryptographic Message Syntax (CMS) SignedData op in Contents (ISO 32000-2 §12.8.1). De Quick-fallback gebruikt een begrensde scan van de documentbytes om de versie, een schatting van het aantal pagina’s en de vlaggen voor aanwezige versleuteling, handtekening en bijlage af te leiden.

API-oppervlak

Maak new Inspector() aan en roep vervolgens ->inspect(string $pdfData, InspectConfig::quick()) aan. Dit levert een InspectResult op met $pdfVersion, $pageCount, $isEncrypted, $hasSigned, $hasAttachments, $fileSizeBytes, $riskFlags en de hasRisks()-helper.

Codevoorbeeld — Quick start

<?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',
);

Codevoorbeeld — Productie

Dit zelfstandige programma draait in de cookbook-harness. Het komt overeen met examples/39-parse-and-inspect-pdf.php: het bouwt een kleine PDF met meerdere pagina’s in het geheugen, leest er met de Quick-fallback de structurele feiten uit en routeert op basis van die feiten, nooit op basis van een vertrouwensoordeel. De routeringstak is illustratief. Vervang die door je eigen pijplijn, verificatiewachtrij en quarantaine.

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

Verwachte standaarduitvoer (STDOUT) (versie en grootte zijn afhankelijk van de build; de demo-PDF is niet versleuteld, niet ondertekend en bevat geen risicovlaggen):

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

Randgevallen en valkuilen

Quick is triage, geen validatie. Het rapporteert wat aanwezig is en wat ontbreekt. Het verifieert geen handtekeningen, ontsleutelt geen inhoud en stelt geen conformiteit vast. Behandel het resultaat als routeringsinvoer.
Het pagina-aantal is een schatting. De Quick-fallback telt markeringen van pagina-objecten. Een bewust misvormde objectgrafiek kan het aantal vertekenen. Gebruik de door Spectrum ondersteunde diepten wanneer je een exact aantal nodig hebt.
Standard/Full hebben de sidecar nodig. new InspectConfig() (diepte Standard) en InspectConfig::full() vereisen de Spectrum-sidecar. Ze werpen INSPECT-SIDECAR-001 wanneer deze niet beschikbaar is en degraderen niet stilzwijgend naar Quick.
Lege invoer. Het doorgeven van een lege string werpt een inspect-uitzondering met “PDF data must not be empty”.
Reikwijdte van de versleutelingsvlag. De vlag weerspiegelt een /Encrypt-trailervermelding. Een gemarkeerd bestand ontsleutelt de inspector niet.

Prestaties

De Quick-fallback gebruikt een begrensde scan, geen volledige parse. Gebruik deze modus om grote hoeveelheden binnenkomende bestanden vooraf te routeren voordat zwaardere verwerking plaatsvindt.

Beveiligingsopmerkingen

De inspector draait binnen het proces en leest alleen structurele markeringen. Er verlaten geen documentbytes de host en er wordt geen documenttekst geëxtraheerd. Een risicovlag, zoals ingesloten JavaScript, is een adviserend routeringssignaal. Het is geen bewering dat het bestand veilig of onveilig is.

Conformiteit

Verklaring	Specificatie	Clausule
De bestandsheader legt de PDF-versie vast.	ISO 32000-2	§7.5.2
De trailer-`/ID` is een bestands-id van twee byte strings.	ISO 32000-2	§7.5.5
Een handtekeningwoordenboek-`Contents` bevat DER CMS SignedData.	ISO 32000-2	§12.8.1

Dit recept rapporteert uitsluitend structurele feiten. Het beweert niet dat het bestand geldig, veilig of conform is.

Commerciële context

De inspectiedieptes Standard en Full lopen via de Spectrum-sidecar. Ze voegen rijkere analyse van objecten, lettertypen en afbeeldingen toe. De hier gedocumenteerde Quick-fallback is Core en werkt offline.