Generar salida de archivado PDF/A-4

De un vistazo

Esta receta genera una salida de archivado PDF/A-4 (ISO 19005-4) mediante el PdfAManager de Pro. Al guardar, NextPDF configura el OutputIntent, el perfil ICC incrustado y los metadatos de identificación. NextPDF genera una salida pensada para ser conforme; un validador independiente determina la conformidad. La receta toma como base examples/32-pdfa4-icc.php.

Instalación

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

PDF/A-4 es una funcionalidad de nivel Pro. En una instalación con solo el núcleo, enablePdfA() lanza InvalidConfigException. El mensaje indica la capacidad security.pdfa que falta y la solución composer require nextpdf/pro. El paso de verificación requiere un validador de PDF/A en PATH. Los ejemplos usan veraPDF con --flavour 4.

Resumen conceptual

PDF/A-4 es el perfil de archivado ISO 19005-4 construido sobre ISO 32000-2 (PDF 2.0). Un archivo conforme es determinista en color y autónomo. Declara un OutputIntent que referencia un perfil ICC de destino incrustado, de modo que el color pueda reproducirse sin recursos externos (§6.2.3). Todos los programas de fuente están incrustados (§6.2.10.4.1). El documento incluye metadatos de identificación pdfaid en XMP (§6.7.3). El archivo no está cifrado (§6.6.4: PDF/A prohíbe la clave de tráiler Encrypt).

NextPDF modela PDF/A con el enum tipado ConformanceMode. enablePdfA() instancia el PdfAManager de Pro, de forma predeterminada con ConformanceMode::PdfA4. El gestor configura el OutputIntent, el flujo ICC y los esquemas de extensión XMP durante save(). Los discriminadores pdfaPart() y pdfaConformanceLetter() mantienen los metadatos pdfaid:part / pdfaid:conformance alineados con la variante seleccionada (base 4, 4e, 4f). El perfil base no emite ninguna letra pdfa:conformance, tal como exige la parte.

Superficie de la API

La superficie de la API se genera a partir de PHPDoc. Los puntos de entrada clave:

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

Ejemplo de código: Inicio 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";

Ejemplo de código: Producción

Este es el programa autónomo ejecutable en el arnés. El invocador de producción convierte el veredicto del validador en la compuerta de compilación. Una llamada correcta a save() demuestra que NextPDF emitió los artefactos; solo el validador demuestra la conformidad.

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

La salida esperada en STDOUT, en un host con nextpdf/pro instalado y un verapdf que informa de que el archivo es conforme, es:

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

En un host con solo el núcleo, el programa termina con un código distinto de cero tras mostrar PDF/A-4 requires nextpdf/pro. Run: composer require nextpdf/pro en STDERR. Si verapdf informa de un problema, el programa termina con un código distinto de cero tras mostrar veraPDF FAILED — output is not PDF/A-4 conforming. La redacción atribuye el veredicto a veraPDF: NextPDF no afirma que haya conformidad con PDF/A-4.

Casos límite y trampas

• Compuerta de Pro. En una instalación con solo el núcleo, enablePdfA() lanza InvalidConfigException. El mensaje indica security.pdfa y la solución composer require nextpdf/pro. Consultar primero el registro para obtener un mensaje limpio para el operador.
• Conflicto de cifrado. Llamar a setEncryption(), useAesGcm() o setPublicKeyEncryption() en un documento PDF/A lanza una excepción de incompatibilidad, sea cual sea el orden de llamada: PDF/A-4 prohíbe la clave de tráiler Encrypt (ISO 19005-4 §6.6.4).
• Variante de conformidad. Pasar el PdfAVersion de Pro a enablePdfA() para 4e (ingeniería, 3D) o 4f (archivos adjuntos). El perfil base no emite ninguna letra pdfa:conformance; 4e/4f fijan E/F. El discriminador ConformanceMode mantiene pdfaid:part coherente.
• El etiquetado es independiente. El PDF/A-4 base trata el etiquetado como opcional. Para un entregable accesible y de archivado, activar el modo etiquetado y PDF/A por separado; consultar la receta de PDF/UA-2.
• La compuerta es el validador. Una llamada correcta a save() significa que los artefactos se emitieron, no que el archivo sea conforme. No afirmar la conformidad con PDF/A-4 hasta que el validador la apruebe.

Rendimiento

El OutputIntent añade un flujo de perfil ICC (unos cientos de KB para sRGB) y el paquete XMP. La incrustación de fuentes domina el tamaño cuando el documento usa fuentes fuera del conjunto base de 14. Para documentos de archivado típicos, la receta se mantiene dentro del presupuesto de 2000 ms / 128 MB. Se aplica el perfil de reproducibilidad semántica: un entregable orientado al validador se compara por el AST estructural y los metadatos, en lugar de por los bytes sin procesar.

Notas de seguridad

Residencia de datos y mitigaciones de PII

La salida de archivado es, por diseño, longeva y autónoma. Cualquier dato personal incluido en el contenido persiste durante la vida útil del archivo. El perfil ICC incrustado y los metadatos viajan con el archivo. Aplicar la política de retención y minimización antes de archivar. PDF/A-4 no tiene semántica de redacción.

Telemetría segura y depuración de registros

La receta escribe únicamente una línea fija de progreso. La salida de veraPDF puede incluir fragmentos de contenido: mantener los registros del validador fuera de los destinos de registro compartidos para documentos con contenido sensible.

Modelo de amenazas

PDF/A-4 es un perfil de fidelidad de archivado, no un control de integridad ni de autenticidad. No firma el archivo ni deja evidencia de manipulación. Combinarlo con una firma cuando la procedencia importe. Una receta aparte cubre la firma. El cifrado es mutuamente excluyente con PDF/A según la especificación.

Comportamiento en modo FIPS

Esta recipe no realiza ninguna operación criptográfica. El modo FIPS no cambia su comportamiento. PDF/A-4 prohíbe el cifrado, así que no se selecciona ningún cifrador.

Conformidad

Declaración	Especificación	Cláusula	reference_id
PDF/A-4 requiere un OutputIntent que referencia un perfil ICC incrustado.	ISO 19005-4	§6.2.3
El color es independiente del dispositivo gracias al perfil de destino de salida.	ISO 19005-4	§6.2.4.3
Todos los programas de fuente están incrustados.	ISO 19005-4	§6.2.10.4.1
El documento lleva identificación pdfaid en XMP.	ISO 19005-4	§6.7.3
El cifrado está prohibido en PDF/A-4.	ISO 19005-4	§6.6.4
Un validador, no el productor, decide la conformidad.	ISO 19005-4	§6.7.3

NextPDF genera una salida pensada para ser conforme con PDF/A-4. El soporte no equivale a conformidad; un perfil probado no equivale a certificación. Esta receta no afirma la conformidad; un validador independiente (por ejemplo, veraPDF) realiza esa determinación. Convertir su veredicto en la compuerta de compilación.

Consulta también

• Módulo de conformidad
• Página principal de conformidad con PDF/A-4
• Emitir un árbol de estructura etiquetado para PDF/UA-2
• Validar la conformidad con un oráculo externo