Produce PDF/A-4 archival output

At a glance

Use this recipe to produce PDF/A-4 (International Organization for Standardization (ISO) 19005-4) archival output with the Pro PdfAManager. When you save, NextPDF schedules the OutputIntent, embedded International Color Consortium (ICC) profile, and identification metadata. NextPDF produces output intended to conform; an independent validator decides conformance. The recipe follows examples/32-pdfa4-icc.php.

Install

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

PDF/A-4 is a Pro-tier feature. In a Core-only install, enablePdfA() raises InvalidConfigException. The message names the missing security.pdfa capability and points to the composer require nextpdf/pro remedy. For verification, you need a PDF/A validator on PATH. The examples use veraPDF with --flavour 4.

Conceptual overview

PDF/A-4 is the ISO 19005-4 archival profile built on ISO 32000-2 (PDF 2.0). A conforming file is colour-deterministic and self-contained. It declares an OutputIntent that references an embedded ICC destination profile, so colour reproduces without external resources (§6.2.3). Every font program is embedded (§6.2.10.4.1). The document carries pdfaid identification metadata in Extensible Metadata Platform (XMP) (§6.7.3). The file is not encrypted (§6.6.4 — PDF/A prohibits the Encrypt trailer key).

NextPDF models PDF/A with the typed ConformanceMode enum. enablePdfA() instantiates the Pro PdfAManager and defaults to ConformanceMode::PdfA4. During save(), the manager schedules the OutputIntent, ICC stream, and XMP extension schemas. The pdfaPart() and pdfaConformanceLetter() discriminators keep the pdfaid:part / pdfaid:conformance metadata aligned with the selected variant (base 4, 4e, 4f). The base profile emits no pdfa:conformance letter, as the part requires.

API surface

The application programming interface (API) surface is generated from PHPDoc. Use these key entry points:

\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 and ConformanceMode::pdfaConformanceLetter(): string

Code sample — Quick start

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

Code sample — Production

Use this self-contained program in a harness. In production, make the validator verdict the build gate. A successful save() proves that NextPDF emitted the artifacts; only the validator proves conformance.

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

On a host with nextpdf/pro installed and a verapdf that reports the file conforming, expected standard output (STDOUT) is:

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

On a Core-only host, the program exits non-zero after writing PDF/A-4 requires nextpdf/pro. Run: composer require nextpdf/pro to standard error (STDERR). If verapdf reports a problem, the program exits non-zero after veraPDF FAILED — output is not PDF/A-4 conforming. The wording attributes the verdict to veraPDF; NextPDF does not assert PDF/A-4 conformance.

Edge cases & gotchas

Pro gate. In a Core-only install, enablePdfA() throws InvalidConfigException. The message names security.pdfa and the composer require nextpdf/pro remedy. Probe the registry first to show a clean operator message.
Encryption conflict. If you call setEncryption(), useAesGcm(), or setPublicKeyEncryption() on a PDF/A document, NextPDF raises an incompatibility exception in either call order. PDF/A-4 prohibits the Encrypt trailer key (ISO 19005-4 §6.6.4).
Conformance variant. Pass the Pro PdfAVersion to enablePdfA() for 4e (engineering, 3D) or 4f (file attachments). The base profile emits no pdfa:conformance letter; 4e/4f set E/F. The ConformanceMode discriminator keeps pdfaid:part consistent.
Tagging is independent. PDF/A-4 base treats tagging as optional. For a deliverable that is accessible and archival, enable tagged mode and PDF/A separately; see the PDF/UA-2 recipe.
The gate is the validator. A successful save() means the artifacts were emitted, not that the file conforms. Do not state PDF/A-4 conformance until the validator passes.

Performance

The OutputIntent adds one ICC profile stream (a few hundred KB for sRGB) plus the XMP packet. Font embedding dominates size when the document uses non-base-14 fonts. For typical archival documents, the recipe stays within the 2000 ms / 128 MB budget. The semantic reproducibility profile applies: compare a validator-oriented deliverable by structural abstract syntax tree (AST) plus metadata rather than raw bytes.

Security notes

Data Residency & PII Mitigations

Archival output is long-lived and self-contained by design. Any personal data in the content persists for the archive lifetime. The embedded ICC profile and metadata travel with the file. Apply retention and minimisation policy before archiving. PDF/A-4 has no redaction semantics.

Safe Telemetry & Log Scrubbing

The recipe writes only a fixed progress line. veraPDF output can include content fragments; keep validator logs out of shared log sinks for documents with sensitive content.

Threat model

PDF/A-4 is an archival-fidelity profile, not an integrity or authenticity control. It does not sign the file or make tampering evident. Combine it with a signature when provenance matters. A separate recipe covers the signature. Encryption is mutually exclusive with PDF/A by spec.

FIPS-mode behavior

This recipe performs no cryptographic operation. Federal Information Processing Standards (FIPS) mode does not change its behavior. PDF/A-4 prohibits encryption, so no cipher is selected.

Conformance

Statement	Spec	Clause
PDF/A-4 requires an OutputIntent referencing an embedded ICC profile.	ISO 19005-4	§6.2.3
Colour is device-independent through the output destination profile.	ISO 19005-4	§6.2.4.3
Every font program is embedded.	ISO 19005-4	§6.2.10.4.1
The document carries pdfaid identification in XMP.	ISO 19005-4	§6.7.3
Encryption is prohibited in PDF/A-4.	ISO 19005-4	§6.6.4
A validator, not the producer, decides conformance.	ISO 19005-4	§6.7.3

NextPDF produces output intended to conform to PDF/A-4. Support is not conformance; a tested profile is not certification. This recipe does not assert conformance; an independent validator, such as veraPDF, makes that determination. Make its verdict the build gate.