Validare la conformità: pre-controllo in-process e oracolo esterno

In breve

Questa ricetta esegue i validatori di conformità in-process, scritti in puro PHP, di NextPDF come rapido pre-controllo strutturale, quindi affida la decisione autorevole sulla conformità a un validatore indipendente. I controlli in-process sono necessari, ma non sufficienti: un esito pulito è un fatto strutturale, non un verdetto di conformità. La ricetta è supportata da examples/33-validate-conformance.php e dal relativo harness tests/Cookbook/Php/ValidateConformanceRecipeTest.php.

Installazione

composer require nextpdf/core:^3

I validatori in-process non richiedono alcuna toolchain esterna. Il gate autorevole richiede un validatore esterno nel PATH. L’esempio usa veraPDF. Non è necessario alcun pacchetto Pro o Enterprise.

Panoramica concettuale

NextPDF include validatori in-process nel namespace \NextPDF\Compliance\Validator. Verificano invarianti normativi specifici senza eseguire un processo esterno:

• PdfRValidator — controlli sul flusso di byte per ISO 23504-1 (PDF/R-1) §5/§6: l’allowlist dell’intestazione del file, gli oggetti di generazione 0, l’allowlist degli operatori del contenuto di pagina del §6.5.7 (solo q/Q/cm/Do) e l’allowlist delle chiavi del dizionario Info del §6.4.3. Restituisce un elenco piatto di PdfRValidationFinding[]; un elenco vuoto significa che ogni controllo del §6 sottoposto a gate è stato superato.
• ArlingtonValidator — esegue la grammatica Arlington leggibile da macchina della PDF Association in modalità solo report: non sottopone mai a gate la build e registra l’hash SHA del commit della grammatica fissata in ogni finding, così i consumatori dell’audit possono correlarlo a uno snapshot upstream noto.

Questi controlli hanno un ambito deliberatamente circoscritto. Rilevano lo scostamento tra un contratto di emissione e una specifica, ma non stabiliscono la conformità ISO per un profilo come PDF/A-4 o PDF/UA-2. Tale determinazione spetta a un validatore indipendente, il cui verdetto è il gate della build (ISO 19005-4 §6.7.3 lo esplicita per PDF/A). La ricetta mantiene chiaro il confine: esegue il pre-controllo in-process, quindi stampa ed esegue il comando dell’oracolo esterno che decide.

Il diagramma seguente mostra il gate a due fasi. Lo regola un solo principio: solo il verdetto dell’oracolo esterno può essere riportato come conformità.

Diagram

Superficie dell’API

La superficie dell’API è generata da PHPDoc. Questi sono i principali entry point:

• \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 per i byte grezzi)

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

In produzione, il chiamante tratta il validatore in-process come un gate economico che fallisce rapidamente in presenza di scostamenti strutturali evidenti, quindi esegue l’oracolo esterno come decisione autorevole sulla conformità. Solo il verdetto dell’oracolo può essere riportato come conformità.

examples/33-validate-conformance.php (gate core)

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

Eseguire l’esempio con php examples/33-validate-conformance.php. L’esempio crea un PDF ordinario, quindi stampa i finding in-process. È previsto che un PDF ordinario produca finding PDF/R-1: è proprio questo il punto didattico. L’esempio stampa quindi il comando autorevole dell’oracolo esterno.

Casi limite e insidie

• Necessario, ma non sufficiente. Un elenco vuoto di finding di PdfRValidator significa che i controlli del §6 sottoposti a gate sono stati superati, nulla di più. Non è un’attestazione di conformità PDF/A-4 o PDF/UA-2. Non riportare mai la conformità basandosi solo su un risultato in-process.
• Un PDF ordinario non supera PDF/R-1 per scelta progettuale. PDF/R-1 è un profilo raster solo per immagini; un normale PDF di testo produce legittimamente finding del §6.5.7 e del §6.4.3. L’esempio lo dimostra di proposito per evidenziare che l’output in-process è un fatto strutturale, non un verdetto.
• Arlington è solo report. ArlingtonValidator::validateReportOnly() non solleva mai eccezioni e non sottopone mai a gate. In modalità di sola grammatica emette un finding info che attesta il caricamento dello SHA della grammatica fissata; restituisce un elenco vuoto quando la grammatica non è materializzata. Non basarvi un gate pass/fail — è un artefatto di verifica incrociata.
• Byte rispetto a file. PdfRValidator::validate() accetta la stringa di byte grezzi (OutputDestination::String); l’oracolo esterno richiede un percorso di file. Rendere persistente il documento con save() per il passaggio all’oracolo.
• Input vuoto. Il passaggio di una stringa vuota o priva di intestazione a PdfRValidator::validate() restituisce un finding di errore §6.2.2 anziché sollevare un’eccezione. Controllare l’elenco dei finding; non dare per scontata un’eccezione.

Prestazioni

I validatori in-process eseguono scansioni regex e dei byte in un singolo passaggio sul PDF. Sono veloci e leggeri in termini di allocazione per i documenti tipici e rimangono entro il budget di 2000 ms / 128 MB. Quando presente, l’oracolo esterno domina il tempo di parete, ma viene eseguito fuori dal processo. Si applica il profilo di riproducibilità semantica. Il valore dell’esempio risiede nel comportamento di convalida osservabile; l’harness verifica tale comportamento tramite un confronto di AST strutturale più metadati.

Note sulla sicurezza

Residenza dei dati e mitigazioni per i dati personali (PII)

I validatori leggono i byte del documento in-process e nulla esce dal processo. L’oracolo esterno, tuttavia, riceve il file. Se si esegue un validatore ospitato, il contenuto del documento esce dal proprio perimetro. Per contenuti sensibili preferire un binario di validazione locale, oppure oscurare i dati prima di convalidare.

Telemetria sicura e pulizia dei log

I finding possono citare percorsi di oggetti e frammenti di operatori. L’esempio scrive i finding su STDERR e una riga di avanzamento fissa su STDOUT. Per i documenti sensibili, mantenere i log dei finding fuori dai sink condivisi. Non registrare mai nei log i byte grezzi del PDF.

Modello di minaccia

Un esito in-process pulito non è un segnale di integrità o autenticità. Un produttore ostile può creare un file che supera i controlli in-process circoscritti ma non supera il validatore completo, oppure che è ben formato ma fuorviante. Trattare il superamento in-process come un filtro rapido, mai come una garanzia di fiducia.

Comportamento in modalità FIPS

Questa ricetta non esegue alcuna operazione crittografica. La modalità FIPS non ne modifica il comportamento. Non avviene alcuna firma, cifratura o digest di materiale di trust.

Conformità

Affermazione	Specifica	Clausola	reference_id
Il contenuto di pagina PDF/R-1 utilizza solo l’allowlist degli operatori q/Q/cm/Do.	ISO 23504-1	§6.5.7
Le pagine PDF/R-1 sono contenuto raster di sole immagini.	ISO 23504-1	§6.5.5
PDF/R-1 vincola le chiavi del dizionario delle informazioni del documento.	ISO 23504-1	§6.4.4
La grammatica Arlington è una verifica incrociata del modello a oggetti leggibile da macchina.	Arlington PDF Model	grammatica
È un validatore, non il produttore, a decidere la conformità.	ISO 19005-4	§6.7.3

I validatori in-process di NextPDF verificano invarianti normativi specifici. Il supporto non è conformità; la convalida non è certificazione. Un esito in-process pulito non stabilisce la conformità ISO; è un validatore indipendente (per esempio veraPDF) a effettuare tale determinazione. Rendere il suo verdetto il gate della build.

Vedere anche

• Modulo Compliance
• Pagina di panoramica sulla conformità
• Produrre output PDF/A-4
• Emettere un albero di struttura PDF/UA-2 con tag