Tworzenie wyniku PDF/A-4 i bramka zgodności oparta na veraPDF

W skrócie

Ten przewodnik pokazuje, jak utworzyć wynik w formacie Portable Document Format/Archive (PDF/A-4) za pomocą PdfAManager w wersji Premium, uruchomić veraPDF i wykorzystać jego werdykt jako bramkę kompilacji. NextPDF zapisuje artefakty; o zgodności decyduje walidator. Opisany przebieg odpowiada examples/32-pdfa4-icc.php.

Wymagania wstępne

Zainstalowany Core: composer require nextpdf/core:^3.
Zainstalowany Premium: composer require nextpdf/pro. PDF/A-4 należy do warstwy Premium (Architecture Decision Record ADR-011). Bez Premium enablePdfA() zgłasza wyjątek InvalidConfigException ze ścieżką uaktualnienia.
veraPDF dostępne w zmiennej PATH na potrzeby kroku bramki.

Przepis

Sprawdź wpis security.pdfa w rejestrze możliwości, aby instalacja zawierająca wyłącznie Core wyświetliła czytelny komunikat zamiast śladu stosu.
Utwórz dokument, a następnie wywołaj enablePdfA() przed dodaniem zawartości.
Ustaw metadane i dodaj zawartość. Nie wywołuj setEncryption(); PDF/A zabrania klucza Encrypt.
Zapisz dokument. Podczas save() PdfAManager dodaje OutputIntent, osadzony profil International Color Consortium (ICC) oraz schematy rozszerzeń Extensible Metadata Platform (XMP).
Uruchom verapdf --flavour 4 dla wyniku. Oznacz kompilację jako nieudaną, jeśli polecenie zakończy się kodem różnym od zera. Bramką jest werdykt walidatora.

Pełny przykład

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

Oczekiwane wyjście

Gdy veraPDF zwraca wynik pozytywny:

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

Gdy brakuje pakietu Premium, skrypt kończy się kodem różnym od zera, podaje komunikat wskazujący konkretną czynność do wykonania i nie zapisuje pliku.

Przypadki brzegowe

Bramka Premium. W instalacji zawierającej wyłącznie Core enablePdfA() zgłasza wyjątek InvalidConfigException, który wskazuje security.pdfa i podaje rozwiązanie composer require nextpdf/pro. Dlatego najpierw sprawdź rejestr.
Konflikt szyfrowania. Wywołanie setEncryption(), useAesGcm() lub setPublicKeyEncryption() na dokumencie PDF/A zgłasza wyjątek niezgodności niezależnie od kolejności wywołań. PDF/A zabrania klucza Encrypt w trailerze.
Wariant zgodności. Przekaż PdfAVersion do enablePdfA(), aby wybrać 4e lub 4f. Wartością domyślną jest 4.
Bramką jest walidator, a nie silnik. Pomyślne save() oznacza, że NextPDF wygenerował artefakty wymagane przez PDF/A-4. Samo w sobie nie dowodzi to zgodności. To veraPDF potwierdza zgodność; w tym przepisie jego werdykt jest bramką. Nie deklaruj, że plik jest zgodny z PDF/A-4, dopóki walidator nie zwróci wyniku pozytywnego.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Plik PDF/A-4 może określać swoją charakterystykę kolorów za pomocą OutputIntent PDF/A, który odwołuje się do osadzonego profilu International Color Consortium (ICC). Kolor niezależny od urządzenia można też określić bezpośrednio; §6.2.4.1.	ISO 19005-4	§6.2.3
Szyfrowanie jest zabronione w PDF/A-4.	ISO 19005-4	§6.6.4
PDF/A-4 umieszcza identyfikację pdfaid w metadanych Extensible Metadata Platform (XMP).	ISO 19005-4	§6.7.5

To walidator potwierdza zgodność. Biblioteka tworzy wynik zaprojektowany pod zgodność; decyduje walidator.