產生 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（裁決器）認定。