Generare output di archiviazione PDF/A-4

In breve

Questa ricetta genera output di archiviazione PDF/A-4 (ISO 19005-4) tramite il PdfAManager Pro. Al momento del salvataggio, NextPDF predispone l’OutputIntent, il profilo ICC incorporato e i metadati di identificazione. NextPDF produce output destinato a essere conforme; la conformità viene determinata da un validatore indipendente. La ricetta si basa su examples/32-pdfa4-icc.php.

Installazione

composer require nextpdf/core:^3
composer require nextpdf/pro

PDF/A-4 è una funzionalità di livello Pro. In un’installazione solo Core, enablePdfA() genera InvalidConfigException. Il messaggio indica la capability security.pdfa mancante e la correzione composer require nextpdf/pro. La fase di verifica richiede un validatore PDF/A nel PATH. Gli esempi usano veraPDF con --flavour 4.

Panoramica concettuale

PDF/A-4 è il profilo di archiviazione ISO 19005-4 basato su ISO 32000-2 (PDF 2.0). Un file conforme ha una resa cromatica deterministica ed è autonomo. Dichiara un OutputIntent che fa riferimento a un profilo di destinazione ICC incorporato, così il colore può essere riprodotto senza risorse esterne (§6.2.3). Ogni programma di font è incorporato (§6.2.10.4.1). Il documento contiene i metadati di identificazione pdfaid in XMP (§6.7.3). Il file non è cifrato (§6.6.4 — PDF/A vieta la chiave del trailer Encrypt).

NextPDF modella PDF/A tramite l’enum tipizzata ConformanceMode. enablePdfA() istanzia il PdfAManager Pro e usa come valore predefinito ConformanceMode::PdfA4. Il manager predispone l’OutputIntent, il flusso ICC e gli schemi di estensione XMP durante save(). I discriminatori pdfaPart() e pdfaConformanceLetter() mantengono i metadati pdfaid:part / pdfaid:conformance allineati alla variante selezionata (base 4, 4e, 4f). Il profilo base non emette alcuna lettera pdfa:conformance, come previsto dalla parte.

Superficie API

La superficie API viene generata da PHPDoc. I punti di ingresso principali sono:

• \NextPDF\Core\Document::createStandalone(): Document
• Document::enablePdfA(?object $version = null): static
• \NextPDF\Support\CapabilityRegistry::getInstance()->get('security.pdfa')->isAvailable(): bool
• \NextPDF\Conformance\ConformanceMode::PdfA4 / PdfA4e / PdfA4f
• ConformanceMode::pdfaPart(): 2|3|4|null e ConformanceMode::pdfaConformanceLetter(): string

Esempio di codice — Avvio rapido

examples/32-pdfa4-icc.php

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Support\CapabilityRegistry;

$out = __DIR__ . '/output/32-pdfa4-icc.pdf';

// Probe before activating a Pro-gated feature so a Core-only install
// gets an actionable message instead of a stack trace.
$registry = CapabilityRegistry::getInstance();
if (!$registry->get('security.pdfa')->isAvailable()) {
    fwrite(STDERR, "PDF/A-4 requires nextpdf/pro. Run: composer require nextpdf/pro\n");
    exit(1);
}

$doc = Document::createStandalone();
$doc->enablePdfA();                  // defaults to ConformanceMode::PdfA4
$doc->setTitle('Archival Record 2026-0042');
$doc->setLanguage('en');
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'This document targets PDF/A-4.', newLine: true);
$doc->save($out);                    // PdfAManager emits OutputIntent + ICC + XMP here

echo "Created: output/32-pdfa4-icc.pdf\n";

Esempio di codice — Produzione

Questo programma è autonomo ed eseguibile dall’harness. In produzione, il chiamante usa il verdetto del validatore come gate della build. Un save() riuscito dimostra che NextPDF ha emesso gli artefatti; solo il validatore dimostra la conformità.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Exception\InvalidConfigException;
use NextPDF\Support\CapabilityRegistry;

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: (__DIR__ . '/archival.pdf');

if (!CapabilityRegistry::getInstance()->get('security.pdfa')->isAvailable()) {
    fwrite(STDERR, "PDF/A-4 requires nextpdf/pro. Run: composer require nextpdf/pro\n");
    exit(1);
}

try {
    $doc = Document::createStandalone();
    $doc->enablePdfA();                       // ConformanceMode::PdfA4

    $doc->setTitle('Archival Record 2026-0042');
    $doc->setLanguage('en');
    $doc->addPage();
    $doc->setFont('helvetica', '', 12);
    $doc->cell(0, 10, 'Long-term archival record. PDF/A-4 (ISO 19005-4).', newLine: true);

    // Do NOT call setEncryption(): PDF/A prohibits the Encrypt key and
    // the call raises an incompatibility exception in either order.
    $doc->save($out);
} catch (InvalidConfigException $e) {
    fwrite(STDERR, "PDF/A-4 activation failed: {$e->getMessage()}\n");
    exit(1);
}

$exitCode = 0;
$report = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — output is not PDF/A-4 conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — archival.pdf is reported PDF/A-4 conforming\n";

Su un host con nextpdf/pro installato e un verapdf che segnala il file come conforme, l’output STDOUT previsto è:

veraPDF PASS — archival.pdf is reported PDF/A-4 conforming

Su un host solo Core, il programma termina con codice diverso da zero dopo aver scritto PDF/A-4 requires nextpdf/pro. Run: composer require nextpdf/pro su STDERR. Se verapdf segnala un problema, il programma termina con codice diverso da zero dopo veraPDF FAILED — output is not PDF/A-4 conforming. La formulazione attribuisce il verdetto a veraPDF — NextPDF non asserisce la conformità PDF/A-4.

Casi limite e insidie

• Gate Pro. In un’installazione solo Core, enablePdfA() genera InvalidConfigException. Il messaggio indica security.pdfa e la correzione composer require nextpdf/pro. Sondare prima il registry consente di ottenere un messaggio operatore pulito.
• Conflitto di cifratura. La chiamata a setEncryption(), useAesGcm() o setPublicKeyEncryption() su un documento PDF/A genera un’eccezione di incompatibilità in qualsiasi ordine di chiamata — PDF/A-4 vieta la chiave del trailer Encrypt (ISO 19005-4 §6.6.4).
• Variante di conformità. Passare il PdfAVersion Pro a enablePdfA() per 4e (ingegneria, 3D) o 4f (allegati di file). Il profilo base non emette alcuna lettera pdfa:conformance; 4e/4f impostano E/F. Il discriminatore ConformanceMode mantiene coerente pdfaid:part.
• La marcatura è indipendente. PDF/A-4 base considera la marcatura opzionale. Per un deliverable accessibile e di archiviazione, abilitare separatamente la modalità con tag e PDF/A; vedere la ricetta PDF/UA-2.
• Il gate è il validatore. Un save() riuscito significa che gli artefatti sono stati emessi, non che il file sia conforme. Non dichiarare la conformità PDF/A-4 finché il validatore non restituisce esito positivo.

Prestazioni

L’OutputIntent aggiunge un flusso di profilo ICC (alcune centinaia di KB per sRGB) più il pacchetto XMP. L’incorporamento dei font è il fattore principale della dimensione quando il documento usa font non base-14. Nei documenti di archiviazione tipici, la ricetta rimane entro il budget di 2000 ms / 128 MB. Si applica il profilo di riproducibilità semantica: un deliverable orientato al validatore viene confrontato in base all’AST strutturale più i metadati anziché ai byte grezzi.

Note sulla sicurezza

Residenza dei dati e mitigazioni delle PII

L’output di archiviazione è, per progettazione, di lunga durata e autonomo. Qualsiasi dato personale presente nel contenuto persiste per l’intera durata dell’archivio. Il profilo ICC incorporato e i metadati viaggiano con il file. Applicare i criteri di conservazione e minimizzazione prima dell’archiviazione. PDF/A-4 non prevede alcuna semantica di oscuramento.

Telemetria sicura e sanificazione dei log

La ricetta scrive solo una riga di avanzamento fissa. L’output di veraPDF può includere frammenti di contenuto — tenere i log del validatore fuori dalle destinazioni di log condivise per i documenti con contenuto sensibile.

Modello di minaccia

PDF/A-4 è un profilo di fedeltà di archiviazione, non un controllo di integrità o autenticità. Non firma il file né lo rende a prova di manomissione. Abbinarlo a una firma quando la provenienza è importante. Una ricetta separata tratta la firma. La cifratura è mutuamente esclusiva con PDF/A per specifica.

Comportamento in modalità FIPS

Questa ricetta non esegue alcuna operazione crittografica. La modalità FIPS non ne modifica il comportamento. PDF/A-4 vieta la cifratura, pertanto non viene selezionato alcun cifrario.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
PDF/A-4 richiede un OutputIntent che faccia riferimento a un profilo ICC incorporato.	ISO 19005-4	§6.2.3
Il colore è indipendente dal dispositivo grazie al profilo di destinazione di output.	ISO 19005-4	§6.2.4.3
Ogni programma di font è incorporato.	ISO 19005-4	§6.2.10.4.1
Il documento contiene l’identificazione pdfaid in XMP.	ISO 19005-4	§6.7.3
La cifratura è vietata in PDF/A-4.	ISO 19005-4	§6.6.4
È un validatore, non il produttore, a decidere la conformità.	ISO 19005-4	§6.7.3

NextPDF produce output destinato a essere conforme a PDF/A-4. Il supporto non è conformità; un profilo testato non è certificazione. Questa ricetta non asserisce la conformità; tale determinazione spetta a un validatore indipendente (ad esempio veraPDF). Usare il suo verdetto come gate della build.

Vedere anche

• Modulo di conformità
• Pagina di destinazione conformità PDF/A-4
• Emettere un albero di struttura PDF/UA-2 con tag
• Convalidare la conformità con un oracolo esterno