Conformiteit valideren: in-process voorcontrole met externe oracle

In het kort

Gebruik dit recipe om de pure-PHP in-process conformiteitsvalidators van NextPDF als snelle structurele voorcontrole uit te voeren en leg daarna de gezaghebbende conformiteitsbeslissing bij een onafhankelijke validator. In-process controles zijn noodzakelijk, maar niet voldoende: een schoon resultaat is een structureel feit, geen conformiteitsoordeel. Het recipe gebruikt examples/33-validate-conformance.php en de bijbehorende tests/Cookbook/Php/ValidateConformanceRecipeTest.php-harness.

Installeren

composer require nextpdf/core:^3

De in-process validators hebben geen externe toolchain nodig. Voor de gezaghebbende poortstap heb je een externe validator op het PATH nodig. Het voorbeeld gebruikt veraPDF. Je hebt geen Pro- of Enterprise-pakket nodig.

Conceptueel overzicht

NextPDF bevat in-process validators onder \NextPDF\Compliance\Validator. Die verifiëren specifieke normatieve invarianten zonder een extern proces te starten:

PdfRValidator — voert de bytestreamcontroles van ISO 23504-1 (PDF/R-1) §5/§6 uit: de allowlist voor de bestandsheader, generatie-0-objecten, de allowlist voor pagina-inhoudsoperatoren uit §6.5.7 (alleen q/Q/cm/Do) en de allowlist voor Info-dict-sleutels uit §6.4.3. De validator geeft een platte PdfRValidationFinding[] terug; een lege lijst betekent dat elke gecontroleerde §6-check is geslaagd.
ArlingtonValidator — voert de machineleesbare Arlington-grammatica van de PDF Association uit in report-only-modus. Deze validator blokkeert de build nooit en registreert bij elke bevinding de vastgezette commit-SHA van de grammatica, zodat auditors die kunnen correleren met een bekende upstream-snapshot.

Deze controles zijn bewust afgebakend. Ze signaleren afwijkingen tussen een emissiecontract en een specificatie, maar stellen geen ISO-conformiteit vast voor een profiel zoals PDF/A-4 of PDF/UA-2. Een onafhankelijke validator doet die bepaling; het oordeel daarvan is de build-poort (ISO 19005-4 §6.7.3 maakt dit expliciet voor PDF/A). Het recipe houdt die grens duidelijk: het voert de voorcontrole in-process uit en print en draait daarna het externe-oracle-commando dat beslist.

Het onderstaande diagram toont de tweetrapspoort. Eén regel bepaalt de flow: alleen het oordeel van de externe oracle mag als conformiteit worden gerapporteerd.

Diagram

API-oppervlak

Het API-oppervlak wordt gegenereerd uit PHPDoc. Gebruik deze belangrijkste entrypoints:

\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 voor ruwe bytes)

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Behandel de in-process validator in productie als een goedkope poort die snel faalt bij duidelijke structurele afwijkingen. Voer daarna de externe oracle uit voor de gezaghebbende conformiteitsbeslissing. Alleen het oordeel van de oracle mag als conformiteit worden gerapporteerd.

$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";

Voer het voorbeeld uit met php examples/33-validate-conformance.php. Het bouwt een gewone PDF en print de in-process bevindingen. Van een gewone PDF wordt verwacht dat die PDF/R-1-bevindingen oplevert; precies dat is het leerpunt. Daarna print het voorbeeld het gezaghebbende externe-oracle-commando.

Randgevallen en valkuilen

Noodzakelijk, niet voldoende. Een lege bevindingenlijst van PdfRValidator betekent alleen dat de gecontroleerde §6-checks zijn geslaagd. Het is geen conformiteitsclaim voor PDF/A-4 of PDF/UA-2. Rapporteer conformiteit nooit alleen op basis van een in-process resultaat.
Een gewone PDF zakt door PDF/R-1, en dat is bewust zo ontworpen. PDF/R-1 is een rasterprofiel met uitsluitend afbeeldingen; een gewone tekst-PDF levert terecht §6.5.7- en §6.4.3-bevindingen op. Het voorbeeld laat dit bewust zien om het punt te maken: in-process uitvoer is een structureel feit, geen oordeel.
Arlington is uitsluitend rapporterend. ArlingtonValidator::validateReportOnly() gooit nooit een exception en blokkeert nooit. In de modus met alleen de grammatica geeft het één info-bevinding af die aantoont dat de vastgezette grammatica-SHA is geladen; het geeft een lege lijst terug wanneer de grammatica niet is gematerialiseerd. Bouw hier geen pass/fail-poort op — het is een kruiscontrole-artefact.
Bytes versus bestand. PdfRValidator::validate() neemt de ruwe bytestring (OutputDestination::String); de externe oracle heeft een bestandspad nodig. Sla het bestand met save() op voor de oracle-stap.
Lege invoer. Een lege of header-loze string doorgeven aan PdfRValidator::validate() levert een §6.2.2-foutbevinding op in plaats van een exception te gooien. Controleer de bevindingenlijst; ga niet uit van een exception.

Prestaties

De in-process validators gebruiken reguliere-expressie- en bytescans in één doorloop over de PDF. Voor typische documenten zijn ze snel en hebben ze weinig allocaties nodig; ze blijven binnen het budget van 2000 ms / 128 MB. Wanneer de externe oracle aanwezig is, domineert die de wandkloktijd, maar hij draait buiten het proces. Het semantische reproduceerbaarheidsprofiel is van toepassing. De waarde van het voorbeeld zit in het observeerbare validatiegedrag; de harness controleert dat gedrag via een structurele abstracte syntaxisboom (AST) plus een vergelijking van metadata.

Beveiligingsnotities

Datalocatie en PII-mitigaties

De validators lezen de documentbytes in-process; niets verlaat het proces. De externe oracle ontvangt echter wel het bestand. Als je een gehoste validator gebruikt, verlaat documentinhoud je grens. Geef voor gevoelige inhoud de voorkeur aan een lokale validator-binary, of redigeer vóór het valideren.

Veilige telemetrie en logopschoning

Bevindingen kunnen objectpaden en operatorfragmenten citeren. Het voorbeeld schrijft bevindingen naar STDERR en een vaste voortgangsregel naar STDOUT. Houd bevindingslogs bij gevoelige documenten buiten gedeelde sinks. Log nooit de ruwe PDF-bytes.

Dreigingsmodel

Een schoon in-process resultaat is geen signaal van integriteit of authenticiteit. Een vijandige producent kan een bestand maken dat de afgebakende in-process controles doorstaat maar zakt bij de volledige validator, of dat welgevormd maar misleidend is. Behandel een in-process succesuitkomst als een snel filter, nooit als vertrouwen.

Gedrag in FIPS-modus

Dit recipe voert geen cryptografische bewerking uit. De Federal Information Processing Standards (FIPS)-modus verandert het gedrag ervan niet. Er vindt geen ondertekening, versleuteling of digest van vertrouwensmateriaal plaats.

Conformiteit

Bewering	Specificatie	Clausule
PDF/R-1-pagina-inhoud gebruikt uitsluitend de toegestane operatorlijst q/Q/cm/Do.	ISO 23504-1	§6.5.7
PDF/R-1-pagina’s zijn rasterinhoud met uitsluitend afbeeldingen.	ISO 23504-1	§6.5.5
PDF/R-1 beperkt de sleutels van de document information dictionary.	ISO 23504-1	§6.4.4
De Arlington-grammatica is een machineleesbare kruiscontrole van het objectmodel.	Arlington PDF Model	grammatica
Een validator, niet de producent, beslist over conformiteit.	ISO 19005-4	§6.7.3

De in-process validators van NextPDF verifiëren specifieke normatieve invarianten. Ondersteuning is geen conformiteit; validatie is geen certificering. Een schoon in-process resultaat stelt geen ISO-conformiteit vast; een onafhankelijke validator (bijvoorbeeld veraPDF) doet die bepaling. Gebruik dat oordeel als de build-poort.