生成 PDF/A-4 输出，并以 veraPDF oracle（裁决器）把关

重点摘要

这个 recipe（示例）通过 Premium 版 PdfAManager 生成 PDF/A-4 输出，运行 veraPDF，并将其裁决作为构建 gate。库负责生成产物；是否合规由验证器判定。本示例遵循 examples/32-pdfa4-icc.php。

先决条件

已安装 Core：composer require nextpdf/core:^3。
已安装 Premium：composer require nextpdf/pro。PDF/A-4 是 Premium 等级的功能（ADR-011）。如果没有 Premium，enablePdfA() 会抛出 InvalidConfigException，并附上升级路径。
gate 步骤需要 PATH 上有 veraPDF。

示例做法

向能力注册表（capability registry）探查 security.pdfa，这样只安装 Core 的环境会收到清楚的消息，而不是一段 stack trace。
创建文档，并在添加内容前先调用 enablePdfA()。
设置元数据并写入内容。不要调用 setEncryption()；PDF/A 禁止 Encrypt 键。
保存。在 save() 期间，PdfAManager 会安排 OutputIntent、内嵌的 ICC 配置文件以及 XMP 扩展架构。
对输出文件运行 verapdf --flavour 4。只要返回非零退出码，就让构建失败。验证器的裁决就是这道 gate。

完整示例

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

预期输出

当 veraPDF 通过时：

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

当缺少 Premium 包时，这个脚本会以非零码退出，输出一段可据以行动的消息，并且不会写出任何文件。

边界情况

Premium 把关。 在只安装 Core 的环境调用 enablePdfA() 会抛出 InvalidConfigException，消息会指名 security.pdfa，并给出 composer require nextpdf/pro 这道补救方式。先探查 registry。
加密冲突。 在 PDF/A 文档上调用 setEncryption()、useAesGcm() 或 setPublicKeyEncryption()，无论调用顺序如何，都会引发不兼容异常。PDF/A 禁止 Encrypt trailer 键。
合规变体。 将 PdfAVersion 传给 enablePdfA()，即可指定 4e 或 4f。默认值是 4。
把关的是验证器，不是引擎。 save() 成功，代表 NextPDF 已输出 PDF/A-4 所要求的各项产物。但这本身并不能证明合规。是否合规由 veraPDF 断定；本示例就是将它的裁决作为这道 gate。在验证器通过之前，不要声称某个文件符合 PDF/A-4。

合规依据

陈述	规范	条款
PDF/A-4 文件可使用 PDF/A OutputIntent 并引用内嵌的 ICC 配置文件来指定其色彩特性（设备无关的色彩也可以改为直接指定；§6.2.4.1）。	ISO 19005-4	§6.2.3
PDF/A-4 禁止加密。	ISO 19005-4	§6.6.4
PDF/A-4 在 XMP 元数据中带有 pdfaid 标识信息。	ISO 19005-4	§6.7.5

是否合规由验证器断定。库生成的输出意在合规；由 oracle（裁决器）作最终认定。