Crear un PDF etiquetado accesible a partir de HTML

De un vistazo

Esta receta crea un PDF etiquetado a partir de HTML semántico. NextPDF genera un árbol de estructura lógica, el idioma del catálogo y los marcadores de PDF/UA-2. La conformidad la determina un validador. La receta sigue examples/31-pdfua2-tagged.php.

Requisitos previos

Core instalado: composer require nextpdf/core:^3.
Un validador de PDF/UA para el paso de verificación. El ejemplo utiliza veraPDF.

Receta

Crear el documento.
Llamar a enableTaggedPdf() con una etiqueta de idioma BCP-47 antes de llamar a writeHtml(). El pipeline de HTML detecta el modo etiquetado al construir el analizador y conecta el emisor de contenido etiquetado.
Definir los metadatos del documento (título, idioma). setLanguage() es idempotente con enableTaggedPdf().
Escribir HTML semántico. El analizador asigna cada elemento de bloque a un elemento de estructura: h1 a H1, p a P, ul/li a L/LI, table a Table/TR/TD.
Guardar y luego validar con un validador de PDF/UA.

Ejemplo completo

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Step 2 — enable tagged mode BEFORE writeHtml(). The lang argument
// drives the catalog /Lang entry and the structure tree root language.
$doc->enableTaggedPdf(lang: 'en');

// Step 3 — metadata. setLanguage() restates intent; it is idempotent here.
$doc->setTitle('Accessible Report');
$doc->setLanguage('en');

$doc->addPage();

// Step 4 — semantic HTML. Each block element becomes a StructElem; text
// runs are wrapped in BDC/EMC operators with stable MCIDs.
$html = <<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<h2>Findings</h2>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML;

$doc->writeHtml($html);

$doc->save(__DIR__ . '/accessible.pdf');

echo "Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf\n";

Salida esperada

Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf

La salida incluye un árbol de estructura, /MarkInfo << /Marked true >>, la entrada /Lang del catálogo y el marcador XMP pdfuaid:part. Ejecuta el validador para confirmar que están presentes y que son internamente coherentes.

Casos límite

Orden de las llamadas. enableTaggedPdf() después de writeHtml() no etiqueta retroactivamente el contenido que ya se escribió. Primero se debe habilitar el modo etiquetado.
Etiqueta de idioma. Pasar ConformancePolicy::strictUa2() como segundo argumento permite rechazar una etiqueta BCP-47 mal formada en el límite de la API, en lugar de descartarla de forma silenciosa durante la escritura.
Reactivación idempotente. Llamar a enableTaggedPdf() dos veces actualiza el idioma sin reconstruir el árbol de estructura que ya se ha rellenado.
Etiquetado manual. Para contenido que no es HTML, envolver los elementos con beginTag() / endTag(). Los tipos de contenedor (Table, THead, TBody, TFoot, TR, L, LI, y los elementos de agrupación Sect/Div/Art/Aside/BlockQuote) se convierten en elementos de agrupación sin contenido marcado; el contenido en línea suelto colocado directamente dentro de un elemento de agrupación se envuelve en un P sintetizado. Los tipos de hoja (P, H1–H6, TD, TH) obtienen MCID.
El soporte no es conformidad. NextPDF genera los metadatos estructurales que PDF/UA-2 necesita. También expone una advertencia de paridad degradada: para la aprobación en producción, quien llama es responsable de validar con un oráculo externo. Ejecuta un validador antes de afirmar que un archivo es conforme.
Las tablas HTML etiquetadas y los elementos de agrupación pasan veraPDF ua2. Una <table> etiquetada —plana, con colspan/rowspan, paginada entre páginas o anidada en una celda— emite la estructura Table/TR/TH/TD (ISO 32000-2 §14.8; las celdas con expansión llevan los atributos /ColSpan y /RowSpan de la Table 384), y los elementos de agrupación <section>/<div>/<article>/<aside>/<blockquote> emiten estructura de agrupación con el contenido en línea suelto envuelto en un P sintetizado. veraPDF --flavour ua2 no informa de ningún fallo en estos casos. Un caso todavía falla: un elemento de bloque anidado dentro de un elemento en línea —un encabezado dentro de un enlace, <a><h2>…</h2></a>— provoca Link shall not contain Hn, por lo que el contenido de bloque debe mantenerse fuera de los envoltorios en línea. Ejecutar un validador antes de afirmar que un archivo es conforme.

Conformidad

Declaración	Especificación	Cláusula
El contenido real requiere una estructura lógica.	ISO 14289-2	§8.2.2
Los elementos de estructura siguen un anidamiento y un orden de lectura definidos.	ISO 14289-2	§8.2.3

Esta receta muestra cómo producir la estructura etiquetada que respalda la creación accesible. No afirma conformidad con PDF/UA-2; eso lo determina un validador.