Gere saída de arquivamento PDF/A-4

Visão geral

Use esta receita para gerar uma saída de arquivamento PDF/A-4 (International Organization for Standardization (ISO) 19005-4) com o PdfAManager do Pro. Ao salvar, o NextPDF agenda o OutputIntent, o perfil International Color Consortium (ICC) incorporado e os metadados de identificação. O NextPDF produz uma saída destinada à conformidade; um validador independente determina essa conformidade. A receita segue examples/32-pdfa4-icc.php.

Instalação

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

PDF/A-4 é um recurso do nível Pro. Em uma instalação apenas com o Core, enablePdfA() lança InvalidConfigException. A mensagem identifica a capacidade security.pdfa ausente e aponta para a correção composer require nextpdf/pro. Para a verificação, você precisa de um validador de PDF/A no PATH. Os exemplos usam o veraPDF com --flavour 4.

Visão conceitual

PDF/A-4 é o perfil de arquivamento ISO 19005-4 baseado na ISO 32000-2 (PDF 2.0). Um arquivo em conformidade tem cor determinística e é autocontido. Ele declara um OutputIntent que referencia um perfil de destino ICC incorporado, para que a cor seja reproduzida sem recursos externos (§6.2.3). Cada programa de fonte é incorporado (§6.2.10.4.1). O documento carrega metadados de identificação pdfaid em Extensible Metadata Platform (XMP) (§6.7.3). O arquivo não é criptografado (§6.6.4 — PDF/A proíbe a chave de trailer Encrypt).

O NextPDF modela PDF/A com o enum tipado ConformanceMode. enablePdfA() instancia o PdfAManager do Pro e usa o padrão ConformanceMode::PdfA4. Durante save(), o gerenciador agenda o OutputIntent, o stream ICC e os esquemas de extensão XMP. Os discriminadores pdfaPart() e pdfaConformanceLetter() mantêm os metadados pdfaid:part / pdfaid:conformance alinhados à variante selecionada (base 4, 4e, 4f). O perfil base não emite nenhuma letra pdfa:conformance, conforme exigido pela parte.

Superfície da API

A superfície da application programming interface (API) é gerada a partir do PHPDoc. Use estes pontos de entrada:

• \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

Exemplo de código — Início rápido

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

Exemplo de código — Produção

Use este programa autocontido em um harness. Em produção, faça do veredito do validador o gate do build. Um save() bem-sucedido comprova que o NextPDF emitiu os artefatos; somente o validador comprova a conformidade.

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

Em um host com nextpdf/pro instalado e um verapdf que reporte o arquivo como em conformidade, a saída padrão (STDOUT) esperada é:

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

Em um host apenas com o Core, o programa sai com código diferente de zero depois de escrever PDF/A-4 requires nextpdf/pro. Run: composer require nextpdf/pro na saída de erro padrão (STDERR). Se o verapdf reportar um problema, o programa sai com código diferente de zero após veraPDF FAILED — output is not PDF/A-4 conforming. O texto atribui o veredito ao veraPDF; o NextPDF não afirma conformidade com PDF/A-4.

Casos extremos e pegadinhas

• Gate do Pro. Em uma instalação apenas com o Core, enablePdfA() lança InvalidConfigException. A mensagem identifica security.pdfa e a correção composer require nextpdf/pro. Sonde o registro primeiro para exibir uma mensagem clara ao operador.
• Conflito de criptografia. Se você chamar setEncryption(), useAesGcm() ou setPublicKeyEncryption() em um documento PDF/A, o NextPDF lança uma exceção de incompatibilidade em qualquer ordem de chamada. PDF/A-4 proíbe a chave de trailer Encrypt (ISO 19005-4 §6.6.4).
• Variante de conformidade. Passe o PdfAVersion do Pro para enablePdfA() para usar 4e (engenharia, 3D) ou 4f (anexos de arquivo). O perfil base não emite nenhuma letra pdfa:conformance; 4e/4f definem E/F. O discriminador ConformanceMode mantém pdfaid:part consistente.
• A marcação é independente. O PDF/A-4 base trata a marcação como opcional. Para um entregável que seja acessível e de arquivamento, habilite o modo marcado e o PDF/A separadamente; consulte a receita de PDF/UA-2.
• O gate é o validador. Um save() bem-sucedido significa que os artefatos foram emitidos, não que o arquivo está em conformidade. Não afirme conformidade com PDF/A-4 até que o validador aprove o arquivo.

Desempenho

O OutputIntent adiciona um stream de perfil ICC (algumas centenas de KB para sRGB) mais o pacote XMP. A incorporação de fontes domina o tamanho quando o documento usa fontes que não são base-14. Para documentos de arquivamento típicos, a receita permanece dentro do orçamento de 2000 ms / 128 MB. O perfil de reprodutibilidade semântica se aplica: compare um entregável orientado a validador pela abstract syntax tree (AST) estrutural e pelos metadados, em vez de bytes brutos.

Notas de segurança

Residência de dados e mitigações de PII

A saída de arquivamento é de longa duração e autocontida por design. Quaisquer dados pessoais no conteúdo persistem durante toda a vida útil do arquivo. O perfil ICC incorporado e os metadados acompanham o arquivo. Aplique a política de retenção e minimização antes de arquivar. PDF/A-4 não tem semântica de redação.

Telemetria segura e limpeza de logs

A receita escreve apenas uma linha de progresso fixa. A saída do veraPDF pode incluir fragmentos de conteúdo; mantenha os logs do validador fora de sinks de log compartilhados em documentos com conteúdo sensível.

Modelo de ameaças

PDF/A-4 é um perfil de fidelidade de arquivamento, não um controle de integridade ou autenticidade. Ele não assina o arquivo nem torna adulterações evidentes. Combine-o com uma assinatura quando a procedência for importante. Uma receita separada cobre assinatura. A criptografia é mutuamente exclusiva com PDF/A por especificação.

Comportamento no modo FIPS

Esta receita não realiza nenhuma operação criptográfica. O modo Federal Information Processing Standards (FIPS) não altera seu comportamento. PDF/A-4 proíbe a criptografia, portanto nenhuma cifra é selecionada.

Conformidade

Declaração	Especificação	Cláusula	reference_id
PDF/A-4 requer um OutputIntent que referencie um perfil ICC incorporado.	ISO 19005-4	§6.2.3
A cor é independente de dispositivo por meio do perfil de destino de saída.	ISO 19005-4	§6.2.4.3
Cada programa de fonte é incorporado.	ISO 19005-4	§6.2.10.4.1
O documento carrega a identificação pdfaid em XMP.	ISO 19005-4	§6.7.3
A criptografia é proibida em PDF/A-4.	ISO 19005-4	§6.6.4
Um validador, não o produtor, determina a conformidade.	ISO 19005-4	§6.7.3

O NextPDF produz uma saída destinada à conformidade com PDF/A-4. Suporte não é conformidade; um perfil testado não é certificação. Esta receita não afirma conformidade; um validador independente, como o veraPDF, faz essa determinação. Faça do veredito dele o gate do build.

Veja também

• Módulo de conformidade
• Página inicial de conformidade com PDF/A-4
• Emita uma árvore de estrutura PDF/UA-2 marcada
• Valide a conformidade com um oráculo externo