Creare da HTML un PDF taggato per l'accessibilità

In breve

Questa ricetta crea un PDF taggato da HTML semantico. NextPDF genera l’albero della struttura logica, la lingua del catalogo e i marcatori PDF/UA-2. La conformità viene stabilita da un checker. La ricetta segue examples/31-pdfua2-tagged.php.

Prerequisiti

Core installato: composer require nextpdf/core:^3.
Un validatore PDF/UA per la verifica. L’esempio usa veraPDF.

Ricetta

Creare il documento.
Chiamare enableTaggedPdf() con un tag di lingua BCP-47 prima di writeHtml(). La pipeline HTML rileva la modalità taggata durante la costruzione del parser e aggancia l’emettitore del contenuto taggato.
Impostare i metadati del documento (titolo, lingua). setLanguage() è idempotente rispetto a enableTaggedPdf().
Scrivere HTML semantico. Il parser associa ciascun elemento di blocco a un elemento di struttura: h1 a H1, p a P, ul/li a L/LI, table a Table/TR/TD.
Salvare e quindi convalidare con un checker PDF/UA.

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

Output previsto

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

L’output contiene un albero della struttura, /MarkInfo << /Marked true >>, la voce /Lang del catalogo e il marcatore XMP pdfuaid:part. Eseguire il checker per confermare che tali elementi siano presenti e coerenti internamente.

Casi limite

Ordine delle chiamate. enableTaggedPdf() dopo writeHtml() non tagga retroattivamente il contenuto già scritto. Abilitare prima la modalità taggata.
Tag di lingua. Passare ConformancePolicy::strictUa2() come secondo argomento per rifiutare un tag BCP-47 malformato al perimetro dell’API, anziché scartarlo silenziosamente in fase di scrittura.
Ri-abilitazione idempotente. Chiamare enableTaggedPdf() due volte aggiorna la lingua senza ricostruire l’albero della struttura già popolato.
Tagging manuale. Per i contenuti non HTML, delimitare gli elementi con beginTag() / endTag(). I tipi contenitore (Table, THead, TBody, TFoot, TR, L, LI, e gli elementi di raggruppamento Sect/Div/Art/Aside/BlockQuote) diventano elementi di raggruppamento privi di contenuto marcato; il contenuto inline libero collocato direttamente all’interno di un elemento di raggruppamento viene racchiuso in un P sintetizzato. I tipi foglia (P, H1–H6, TD, TH) ottengono gli MCID.
Il supporto non è conformità. NextPDF emette i metadati strutturali richiesti da PDF/UA-2. Espone inoltre un avviso di parità ridotta: ai fini dell’approvazione in produzione, la convalida tramite un oracolo esterno resta responsabilità del chiamante. Eseguire un checker prima di dichiarare che un file è conforme.
Le tabelle HTML taggate e gli elementi di raggruppamento superano veraPDF ua2. Una <table> taggata — semplice, con colspan/rowspan, paginata su più pagine o annidata in una cella — emette la struttura Table/TR/TH/TD (ISO 32000-2 §14.8; le celle che si estendono portano gli attributi /ColSpan e /RowSpan di Table 384), e gli elementi di raggruppamento <section>/<div>/<article>/<aside>/<blockquote> emettono struttura di raggruppamento con il contenuto inline libero racchiuso in un P sintetizzato. veraPDF --flavour ua2 non segnala alcun fallimento per questi casi. Un caso continua a fallire: un elemento di blocco annidato in un elemento inline — un’intestazione dentro un collegamento, <a><h2>…</h2></a> — fa scattare Link shall not contain Hn, quindi tenere il contenuto di blocco al di fuori dei wrapper inline. Eseguire un checker prima di dichiarare che un file è conforme.

Conformità

Dichiarazione	Specifica	Clausola
Il contenuto reale richiede una struttura logica.	ISO 14289-2	§8.2.2
Gli elementi della struttura seguono un annidamento e un ordine di lettura definiti.	ISO 14289-2	§8.2.3

Questa ricetta mostra come produrre la struttura taggata a supporto della creazione accessibile. Non dichiara la conformità PDF/UA-2; tale decisione spetta a un checker.