Crie um PDF marcado para acessibilidade a partir de HTML

Visão geral

Use esta receita para criar um PDF marcado a partir de HTML semântico. O NextPDF grava a árvore de estrutura lógica, o idioma no catálogo e os marcadores PDF/UA-2. A conformidade é determinada por um verificador. Esta receita segue examples/31-pdfua2-tagged.php.

Pré-requisitos

Instale o Core: composer require nextpdf/core:^3.
Use um validador PDF/UA para verificar o resultado. O exemplo usa o veraPDF.

Receita

Crie o documento.
Chame enableTaggedPdf() com uma etiqueta de idioma Best Current Practice (BCP) 47 antes de writeHtml(). O pipeline de HTML detecta o modo marcado ao construir o parser e, então, conecta o emissor de conteúdo marcado.
Defina os metadados do documento (título, idioma). Você pode chamar setLanguage() com segurança em conjunto com enableTaggedPdf() porque ele é idempotente.
Escreva HTML semântico. O parser mapeia cada elemento de bloco para um elemento de estrutura: h1 para H1, p para P, ul/li para L/LI e table para Table/TR/TD.
Salve e valide com um verificador PDF/UA.

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

Saída esperada

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

A saída inclui uma árvore de estrutura, /MarkInfo << /Marked true >>, a entrada /Lang do catálogo e o marcador XMP pdfuaid:part. Execute o verificador para confirmar que esses itens estão presentes e são internamente consistentes.

Casos de borda

Ordem das chamadas. Chamar enableTaggedPdf() depois de writeHtml() não marca retroativamente o conteúdo que já foi gravado. Habilite o modo marcado primeiro.
Etiqueta de idioma. Passe ConformancePolicy::strictUa2() como o segundo argumento para rejeitar uma etiqueta BCP-47 malformada na borda da API, em vez de descartá-la silenciosamente no momento da gravação.
Reativação idempotente. Se você chamar enableTaggedPdf() duas vezes, o NextPDF atualiza o idioma sem reconstruir a árvore de estrutura que você já preencheu.
Marcação manual. Para conteúdo que não venha de HTML, envolva os itens com beginTag() / endTag(). Os tipos de contêiner (Table, TR, L, LI) tornam-se elementos de agrupamento sem conteúdo marcado. Os tipos folha (P, H1–H6, TD) recebem MCIDs.
Suporte não é conformidade. O NextPDF emite os metadados estruturais de que o PDF/UA-2 precisa. Ele também expõe um aviso de paridade degradada: para aprovação em produção, a validação externa por oráculo é responsabilidade de quem chama. Execute um verificador antes de afirmar que um arquivo está em conformidade.

Conformidade

Declaração	Especificação	Cláusula	reference_id
O conteúdo real requer uma estrutura lógica.	ISO 14289-2	§8.2.2
Os elementos de estrutura seguem um aninhamento e uma ordem de leitura definidos.	ISO 14289-2	§8.2.3

Esta receita mostra como produzir a estrutura marcada que dá suporte à criação de documentos acessíveis. Ela não declara conformidade com PDF/UA-2; isso é determinado por um verificador.