Konformität validieren: prozessinterne Vorabprüfung und externes Orakel

Auf einen Blick

Dieses Recipe führt NextPDFs reine PHP-Konformitätsvalidatoren als schnelle strukturelle Vorabprüfung im Prozess aus und leitet anschließend die maßgebliche Konformitätsentscheidung an einen unabhängigen Validator weiter. Prüfungen im Prozess sind notwendig, aber nicht hinreichend: Ein sauberes Ergebnis ist eine strukturelle Tatsache, kein Konformitätsurteil. Das Recipe basiert auf examples/33-validate-conformance.php und dem zugehörigen tests/Cookbook/Php/ValidateConformanceRecipeTest.php-Harness.

Installation

composer require nextpdf/core:^3

Die Validatoren im Prozess benötigen keine externe Toolchain. Der maßgebliche Gate-Schritt benötigt einen externen Validator im PATH. Das Beispiel verweist auf veraPDF. Sie benötigen kein Pro- oder Enterprise-Paket.

Konzeptioneller Überblick

NextPDF stellt unter \NextPDF\Compliance\Validator Validatoren im Prozess bereit. Sie prüfen bestimmte normative Invarianten, ohne einen externen Prozess auszuführen:

PdfRValidator — Byte-Stream-Prüfungen nach ISO 23504-1 (PDF/R-1) §5/§6: die Allowlist für den Datei-Header, Objekte der Generation 0, die Allowlist aus §6.5.7 für Operatoren im Seiteninhalt (nur q/Q/cm/Do) sowie die Allowlist aus §6.4.3 für Schlüssel im Info-Dictionary. Er liefert ein flaches PdfRValidationFinding[]; eine leere Liste bedeutet, dass alle als Gate ausgeführten §6-Prüfungen bestanden wurden.
ArlingtonValidator — wendet die maschinenlesbare Arlington-Grammatik der PDF Association nur berichtend an: Er verwendet sie niemals als Build-Gate und hält bei jedem Befund den angepinnten Grammatik-Commit-SHA fest, damit Audit-Konsumenten gegen einen bekannten Upstream-Snapshot abgleichen können.

Diese Prüfungen sind bewusst eng abgegrenzt. Sie erkennen Drift zwischen einem Emissionsvertrag und einer Spezifikation, stellen aber keine ISO-Konformität für ein Profil wie PDF/A-4 oder PDF/UA-2 fest. Diese Feststellung ist Aufgabe eines unabhängigen Validators, dessen Urteil das Build-Gate ist (ISO 19005-4 §6.7.3 macht das für PDF/A ausdrücklich). Das Recipe zieht diese Grenze klar: Es führt die Vorabprüfung im Prozess aus und gibt dann den Befehl für das entscheidende externe Orakel aus und führt ihn aus.

Das Diagramm unten zeigt das zweistufige Gate. Es gilt nur eine Regel: Nur das Urteil des externen Orakels darf als Konformität gemeldet werden.

Diagram

API-Oberfläche

Die API-Oberfläche wird aus PHPDoc generiert. Die wichtigsten Einstiegspunkte sind:

\NextPDF\Compliance\Validator\PdfRValidator::validate(string $pdfBytes): list<PdfRValidationFinding>
\NextPDF\Compliance\Validator\PdfRValidationFinding (readonly: clause, severity, message)
\NextPDF\Compliance\Validator\ArlingtonValidator::validateReportOnly(string $pdfPath): list<ArlingtonFinding>
\NextPDF\Core\Document::output(?string $filename, OutputDestination $dest): string (OutputDestination::String für rohe Bytes)

Code-Beispiel — Schnellstart

<?php

declare(strict_types=1);

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

use NextPDF\Compliance\Validator\PdfRValidator;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Document under conformance review.', newLine: true);

$bytes = $doc->output(dest: OutputDestination::String);

$findings = (new PdfRValidator())->validate($bytes);

// A finding list is a structural fact, not a conformance verdict.
echo $findings === []
    ? "No in-process PDF/R-1 findings (necessary, not sufficient).\n"
    : count($findings) . " in-process finding(s); not a conformance verdict.\n";

Code-Beispiel — Produktion

Produktionscode behandelt den Validator im Prozess als kostengünstiges Gate, das bei offensichtlicher struktureller Drift schnell fehlschlägt, und führt dann das externe Orakel als maßgebliche Konformitätsentscheidung aus. Nur das Urteil des Orakels darf als Konformität gemeldet werden.

$bytes = $doc->output(dest: OutputDestination::String);
$doc->save($out);

// 1. In-process pre-check — necessary, not sufficient.
$findings = (new PdfRValidator())->validate($bytes);
foreach ($findings as $finding) {
    fwrite(STDERR, sprintf("[%s] §%s — %s\n",
        $finding->severity, $finding->clause, $finding->message));
}

// 2. The authoritative gate — the external validator decides.
$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — not reported conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — the validator reports the file conforming\n";

Führen Sie das Beispiel mit php examples/33-validate-conformance.php aus. Es baut ein gewöhnliches PDF und gibt dann die Befunde aus dem Prozess aus. Bei einem gewöhnlichen PDF ist zu erwarten, dass es PDF/R-1-Befunde erzeugt; genau dieses Ergebnis ist der didaktische Punkt. Anschließend gibt das Beispiel den maßgeblichen Befehl für das externe Orakel aus.

Randfälle & Fallstricke

Notwendig, nicht hinreichend. Eine leere Befundliste von PdfRValidator bedeutet, dass die als Gate ausgeführten §6-Prüfungen bestanden wurden, nicht mehr. Das ist kein PDF/A-4- oder PDF/UA-2-Konformitätsanspruch. Melden Sie Konformität niemals allein aus einem Ergebnis im Prozess.
Ein gewöhnliches PDF scheitert bei PDF/R-1 von vornherein. PDF/R-1 ist ein reines Rasterprofil für Bilder; ein normales Text-PDF erzeugt zu Recht §6.5.7- und §6.4.3-Befunde. Das Beispiel demonstriert das absichtlich, um zu zeigen, dass das Ergebnis im Prozess eine strukturelle Tatsache ist, kein Urteil.
Arlington ist nur berichtend. ArlingtonValidator::validateReportOnly() wirft nie und dient nie als Gate. Im reinen Grammatik-Modus gibt er einen info-Befund aus, der belegt, dass der angepinnte Grammatik-SHA geladen wurde; er liefert eine leere Liste, wenn die Grammatik nicht materialisiert ist. Bauen Sie darauf kein pass/fail-Gate auf — es ist ein Querprüf-Artefakt.
Bytes vs. Datei. PdfRValidator::validate() nimmt den rohen Byte-String entgegen (OutputDestination::String); das externe Orakel benötigt einen Dateipfad. Persistieren Sie mit save() für den Orakel-Schritt.
Leere Eingabe. Wenn Sie einen leeren String oder einen String ohne Header an PdfRValidator::validate() übergeben, liefert er einen §6.2.2-Fehlerbefund, statt eine Exception zu werfen. Prüfen Sie die Befundliste; gehen Sie nicht von einer Exception aus.

Performance

Die Validatoren im Prozess sind Single-Pass-Regex- und Byte-Scans über das PDF. Sie sind für typische Dokumente schnell und allokationsarm und bleiben innerhalb des Budgets von 2000 ms / 128 MB. Sofern vorhanden, dominiert das externe Orakel die Wall-Time, läuft aber außerhalb des Prozesses. Das Profil der semantischen Reproduzierbarkeit gilt. Der Wert des Beispiels liegt in seinem beobachtbaren Validierungsverhalten; der Harness prüft dieses Verhalten über einen Vergleich von strukturellem AST plus Metadaten.

Sicherheitshinweise

Datenresidenz & PII-Minderungen

Die Validatoren lesen die Dokumentbytes im Prozess; nichts verlässt den Prozess. Das externe Orakel erhält jedoch die Datei. Wenn Sie einen gehosteten Validator verwenden, verlässt der Dokumentinhalt Ihre Grenze. Bevorzugen Sie für sensible Inhalte eine lokale Validator-Binary oder schwärzen Sie vor der Validierung.

Sichere Telemetrie & Log-Bereinigung

Befunde können Objektpfade und Operatorfragmente zitieren. Das Beispiel schreibt Befunde nach STDERR und eine feste Fortschrittszeile nach STDOUT. Halten Sie Befund-Logs bei sensiblen Dokumenten aus gemeinsam genutzten Senken heraus. Loggen Sie niemals die rohen PDF-Bytes.

Bedrohungsmodell

Ein sauberes Ergebnis im Prozess ist kein Integritäts- oder Authentizitätssignal. Ein böswilliger Produzent kann eine Datei bauen, die die eng abgegrenzten Prüfungen im Prozess besteht, aber am vollständigen Validator scheitert, oder die wohlgeformt, aber irreführend ist. Behandeln Sie das Bestehen im Prozess als schnellen Filter, niemals als Vertrauensgrundlage.

Verhalten im FIPS-Modus

Dieses Recipe führt keine kryptografische Operation aus. Der FIPS-Modus ändert sein Verhalten nicht. Es findet kein Signieren, kein Verschlüsseln und kein Digest von Vertrauensmaterial statt.

Konformität

Aussage	Spezifikation	Klausel
PDF/R-1-Seiteninhalt verwendet nur die Operator-Allowlist q/Q/cm/Do.	ISO 23504-1	§6.5.7
PDF/R-1-Seiten sind reiner Rasterinhalt aus Bildern.	ISO 23504-1	§6.5.5
PDF/R-1 schränkt die Schlüssel im Dokumentinformations-Dictionary ein.	ISO 23504-1	§6.4.4
Die Arlington-Grammatik ist eine maschinenlesbare Querprüfung des Objektmodells.	Arlington PDF Model	grammar
Über Konformität entscheidet ein Validator, nicht der Produzent.	ISO 19005-4	§6.7.3

NextPDFs Validatoren im Prozess prüfen bestimmte normative Invarianten. Support ist nicht Konformität; Validierung ist nicht Zertifizierung. Ein sauberes Ergebnis im Prozess stellt keine ISO-Konformität fest; ein unabhängiger Validator (zum Beispiel veraPDF) trifft diese Feststellung. Machen Sie dessen Urteil zum Build-Gate.