Conformità: routing di ConformanceMode e limite della convalida

In breve

NextPDF\Conformance contiene l’unico discriminatore che indica al writer quale contratto ISO il documento intende soddisfare. La libreria emette le strutture definite dal contratto; non certifica, né può certificare, che il file risultante sia conforme. Solo un validatore esterno può certificarne la conformità.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Il modulo Conformance espone due tipi pubblici. ConformanceMode è un enum tipizzato che nomina il contratto di destinazione (Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f). ConformancePolicy è un value object immutabile che combina una modalità con interruttori di rigore ortogonali.

La modalità è l’unica fonte di verità per i gate del writer a valle. Prima dell’introduzione di questo enum, il motore deduceva «questo documento è etichettato secondo la specifica?» a partire da flag sparsi. ConformanceMode::isTagged(), isAccessibility(), isArchival(), pdfaPart(), pdfaConformanceLetter() e requiresPdf17() restituiscono ciascuno una risposta tipizzata che il writer legge direttamente. Il catalogo, /MarkInfo, la discendenza dell’intestazione del file e i marcatori XMP pdfaid restano coerenti con l’intento dichiarato.

Va letto con precisione il limite del supporto. NextPDF Core emette strutture definite da questi standard. La norma ISO 19005-4:2020 §6.7.3 specifica lo schema di identificazione che registra quale variante PDF/A un file dichiara. La norma ISO 19005-4:2020 stabilisce che l’effettiva determinazione della conformità avviene come specificato nella sua Clausola 5 — ossia rispetto ai requisiti normativi, tramite uno strumento di verifica, non tramite la libreria che produce il file. La norma ISO 14289-2:2024 §6 inquadra la conformità come una proprietà soddisfatta da un file. L’impostazione di una modalità da parte di NextPDF è un input necessario per un file conforme. Di per sé, non costituisce un risultato di conformità.

È la stessa disciplina Verified-versus-Claimed applicata nella matrice di supporto CSS. Una funzionalità è Verified solo quando esistono un test superato o un’esecuzione dell’oracolo superata, insieme a una clausola citata. Tutto il resto è un’implementazione che la libreria emette — utile, ma non una garanzia di conformità. La conformità è una proprietà del file finale insieme a un validatore, non una promessa della libreria. Convalidare l’output con veraPDF (vedere «Conformità» di seguito).

Un secondo limite è rilevante per i flussi di archiviazione. La creazione di PDF/A-4 — il dizionario OutputIntent, il profilo ICC incorporato e lo schema di estensione XMP — è inclusa nell’estensione nextpdf/pro, non in Core. In un’installazione solo Core, Document::enablePdfA() solleva InvalidConfigException perché la capability security.pdfa non è registrata. Core mantiene comunque il discriminatore ConformanceMode (così l’introspezione e il percorso etichettato PDF/UA-2 funzionano), ma non crea autonomamente un file PDF/A-4.

Superficie API

Tipo	Categoria	Membri principali
NextPDF\Conformance\ConformanceMode	enum: string	Plain, PdfUa1, PdfUa2, PdfA2, PdfA3, PdfA3b, PdfA3u, PdfA4, PdfA4e, PdfA4f; isTagged(), isAccessibility(), isArchival(), requiresPdfUa2PageTabs(), pdfaPart(): ?int, pdfaConformanceLetter(): string, requiresPdf17(): bool
NextPDF\Conformance\ConformancePolicy	final readonly class	__construct(ConformanceMode $mode = PdfUa2, bool $strictUa2 = false, bool $rejectUnvalidatedLang = false, …); lax(), strictUa2(), withUax9IsolateSupport(), withoutAstShadowMode(), withBlackPointCompensation(), withStrictOcspProducedAtTolerance(), withAllowStaleOcsp()

ConformancePolicy applica un’invariante nel costruttore: gli interruttori rigorosi PDF/UA-2 si applicano solo quando la modalità è PdfUa2 e strictUa2 = true forza rejectUnvalidatedLang = true. Le combinazioni incoerenti generano InvalidConfigException invece di degradare silenziosamente.

Esempio di codice — Avvio rapido

<?php

declare(strict_types=1);

use NextPDF\Conformance\ConformanceMode;

$mode = ConformanceMode::PdfA4f;

// Introspect the declared contract — these drive writer-side gates.
$mode->pdfaPart();              // 4
$mode->pdfaConformanceLetter(); // 'F'
$mode->requiresPdf17();         // false (PDF/A-4 is PDF 2.0 lineage)
$mode->isArchival();            // true

Esempio di codice — Produzione

Il percorso di Core che esercita un contratto di conformità end-to-end è la route etichettata PDF/UA-2. Questo è l’esempio eseguibile (examples/31-pdfua2-tagged.php). È anche il target dell’oracolo per il profilo PDF/UA-2 rigoroso.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Set the tagged-PDF contract BEFORE writing content so the HTML pipeline
// wires the TaggedContentEmitter at parser-construction time.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Accessible report');
// … write content …

$doc->save(__DIR__ . '/out/report-ua2.pdf');

// The library has now emitted PDF/UA-2 structures. It has NOT asserted
// conformance. Verify the file with the pinned veraPDF oracle:
//
//   php oracle/run.php pdfua.strict
//
// (Requires the veraPDF Docker image — opt-in; see "Conformance" below.)

Casi limite e insidie

• La creazione di PDF/A-4 è Premium. Document::enablePdfA() genera InvalidConfigException in un’installazione solo Core (security.pdfa non disponibile). Core possiede il discriminatore, non l’emissione di OutputIntent/ICC/XMP. Vedere /specifications/pdfa4/.
• Caso generico e varianti. PdfA4 è il caso generico e restituisce un pdfaConformanceLetter() vuoto. La norma ISO 19005-4:2020 §6.7.3 stabilisce che un file non conforme né a PDF/A-4e né a PDF/A-4f non fornisce alcun pdfa:conformance. Usare PdfA4e / PdfA4f solo per le varianti Annex B / Annex A.
• Il PDF/UA-2 rigoroso è opt-in. ConformancePolicy::lax() è il valore predefinito sicuro per la compatibilità all’indietro. strictUa2() forza /MarkInfo /Marked true e il rifiuto dei valori BCP-47 non convalidati. Abilitarlo su una modalità diversa da PdfUa2 genera un’eccezione.
• isTagged() tiene conto della variante. Plain, PdfA2, PdfA3b e PdfA4e risultano non etichettati. Il writer non deve presumere che una modalità di archiviazione implichi un albero della struttura.
• Impostare una modalità non rende valido il file. L’impostazione di PdfA4 non rende l’output un file PDF/A-4 valido. Eseguire un validatore.

Prestazioni

ConformanceMode e ConformancePolicy sono value type puri: la risoluzione del caso enum e il dispatch match sono O(1) senza allocazioni oltre all’oggetto policy immutabile. Non aggiungono alcun costo misurabile al percorso di scrittura. Il writer domina il budget del modulo (wall_ms: 1500), non il discriminatore. L’oracolo veraPDF è un passaggio CI fuori banda, non parte della generazione del documento.

Note sulla sicurezza

Gli interruttori rigorosi su ConformancePolicy regolano un comportamento di sicurezza fail-closed: securityPkiRfc5280Strict (convalida del percorso RFC 5280 §6), strictOcspProducedAtTolerance (finestra di scarto RFC 6960 §4.2.2.1) e allowStaleOcsp (predefinito false — rifiuta le risposte OCSP prive di nextUpdate). Questi valori predefiniti sono conservativi e passeranno a rigorosi in una futura major release secondo la strategia di compatibilità all’indietro documentata. Vedere il modulo di sicurezza e il modello di minaccia del progetto per i dettagli sul percorso della firma.

Conformità

NextPDF non certifica la conformità. Emette strutture definite dagli standard indicati di seguito; un validatore separato decide se un file è conforme.

Standard	Clausola	Cosa fa NextPDF Core	Stato
ISO 14289-2:2024 (PDF/UA-2)	§6	Emette l’albero della struttura, /MarkInfo /Marked true (rigoroso), /Lang, XMP pdfuaid tramite il percorso etichettato di Core	Profilo Verified: pdfua.strict convalidato dall’oracolo veraPDF (php oracle/run.php pdfua.strict) quando il binario veraPDF è presente (gate opt-in)
ISO 19005-4:2020 (PDF/A-4)	§6.7.3	Emette il discriminatore pdfaid:part / pdfa:conformance tramite ConformanceMode	Claimed (emissione del discriminatore, coperta da unit test); la creazione di file PDF/A-4 è disponibile solo in Premium
ISO 32000-2:2020 (PDF 2.0)	§7.5.2	Struttura di base catalog/document	Claimed (comportamento di base del motore)

Il supporto non è conformità. NextPDF Core emette strutture di identificazione PDF/UA-2 e PDF/A-4 (implementazione comprovata dai test in tests/Unit/Conformance/). La conformità di un file a PDF/A-4 o PDF/UA-2 può essere attestata solo da un validatore che esegue il profilo corrispondente. Secondo la Clausola 5 della norma ISO 19005-4:2020, la determinazione della conformità spetta al validatore, non alla libreria che produce il file.

Il gating di veraPDF dichiara esplicitamente il proprio requisito. L’oracolo (oracle/run.php, oracle/lib/OracleRunner.php) richiama un’immagine Docker veraPDF con versione fissata. Quando Docker o l’immagine non sono presenti, il runner termina con il codice 2 (errore di infrastruttura) e non verifica nulla. Il profilo pdfua.strict è quindi un gate di conformità opt-in: dimostra la conformità solo sulle macchine in cui il binario veraPDF è presente. NextPDF non include alcun validatore incorporato e non avanza alcuna dichiarazione di conformità in sua assenza.

Le citazioni sono parafrasate dal corpus di conformità di NextPDF. I digest reference_id completi a 64 caratteri sono registrati nel front-matter della pagina e in _normative-evidence-conf.md.

Vedere anche

• Modulo Compliance — validatore PDF/R-1, grammatica Arlington, strumenti di ciclo di vita
• Modulo Accessibility — l’emettitore di contenuto etichettato PDF/UA-2
• Mappatura della specifica PDF/A-4 — copertura delle funzionalità ISO 19005-4 e non copertura esplicita
• Mappatura della specifica PDF/UA-2 — mappatura dell’accessibilità ISO 14289-2
• Modulo Security — interruttori rigorosi del percorso della firma