Gere saída PDF/A-4 e use o oráculo veraPDF como gate

Visão geral

Este guia prático gera saída no formato Portable Document Format/Archive (PDF/A-4) com o PdfAManager Premium, executa o veraPDF e usa o veredito dele como gate do build. O NextPDF grava os artefatos; o validador decide a conformidade. O fluxo segue examples/32-pdfa4-icc.php.

Pré-requisitos

Core instalado: composer require nextpdf/core:^3.
Premium instalado: composer require nextpdf/pro. O PDF/A-4 é um recurso da camada Premium (Architecture Decision Record ADR-011). Sem o Premium, enablePdfA() lança InvalidConfigException com uma orientação de upgrade.
veraPDF no PATH para a etapa do gate.

Receita

Consulte security.pdfa no registro de capacidades para que uma instalação somente Core exiba uma mensagem clara em vez de um stack trace.
Crie o documento e chame enablePdfA() antes de adicionar conteúdo.
Defina os metadados e escreva o conteúdo. Não chame setEncryption(); o PDF/A proíbe a chave Encrypt.
Salve o documento. Durante save(), o PdfAManager agenda o OutputIntent, o perfil International Color Consortium (ICC) incorporado e os esquemas de extensão Extensible Metadata Platform (XMP).
Execute verapdf --flavour 4 no arquivo de saída. Faça o build falhar se o comando encerrar com código diferente de zero. O veredito do validador é o gate.

Exemplo completo

<?php

declare(strict_types=1);

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

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

$out = __DIR__ . '/archival.pdf';

// Step 1 — probe before activating a Premium-gated feature.
$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);
}

try {
    $doc = Document::createStandalone();

    // Step 2 — enable PDF/A-4 before content. Defaults to PdfA4.
    $doc->enablePdfA();

    // Step 3 — metadata and content. No setEncryption() on a PDF/A document.
    $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);

    // Step 4 — save. PdfAManager emits OutputIntent + ICC + XMP here.
    $doc->save($out);
} catch (InvalidConfigException $e) {
    fwrite(STDERR, "PDF/A-4 activation failed: {$e->getMessage()}\n");
    exit(1);
}

// Step 5 — the gate. veraPDF, not the library, asserts conformance.
$exitCode = 0;
$output = [];
exec('verapdf --flavour 4 ' . escapeshellarg($out), $output, $exitCode);

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

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

Saída esperada

Quando o veraPDF aprova:

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

Quando o pacote Premium está ausente, o script encerra com código diferente de zero, exibe uma mensagem acionável e não grava nenhum arquivo.

Casos extremos

Gate Premium. Em uma instalação somente Core, enablePdfA() lança InvalidConfigException que menciona security.pdfa e indica a solução composer require nextpdf/pro. Consulte o registro primeiro.
Conflito de criptografia. Chamar setEncryption(), useAesGcm() ou setPublicKeyEncryption() em um documento PDF/A gera uma exceção de incompatibilidade independentemente da ordem de chamada. O PDF/A proíbe a chave de trailer Encrypt.
Variante de conformidade. Passe um PdfAVersion para enablePdfA() para gerar 4e ou 4f. O padrão é 4.
O gate é o validador, não o engine. Um save() bem-sucedido significa que o NextPDF emitiu os artefatos que o PDF/A-4 exige. Por si só, isso não comprova a conformidade. O veraPDF atesta a conformidade; esta receita transforma o veredito dele no gate. Não afirme que um arquivo está em conformidade com o PDF/A-4 antes de o validador aprovar.

Conformidade

Declaração	Especificação	Cláusula
Um arquivo PDF/A-4 pode especificar suas características de cor com um OutputIntent PDF/A que faz referência a um perfil International Color Consortium (ICC) incorporado. Como alternativa, a cor independente de dispositivo pode ser especificada diretamente; §6.2.4.1.	ISO 19005-4	§6.2.3
A criptografia é proibida no PDF/A-4.	ISO 19005-4	§6.6.4
O PDF/A-4 carrega a identificação pdfaid nos metadados Extensible Metadata Platform (XMP).	ISO 19005-4	§6.7.5

O validador atesta a conformidade. A biblioteca produz uma saída destinada à conformidade; o validador decide.