Créer un PDF balisé et accessible à partir de HTML

En bref

Cette recipe crée un PDF balisé à partir de HTML sémantique. NextPDF génère un arbre de structure logique, renseigne la langue du catalogue et ajoute les marqueurs PDF/UA-2. La conformité est déterminée par un vérificateur. Elle suit examples/31-pdfua2-tagged.php.

Prérequis

Core installé : composer require nextpdf/core:^3.
Un vérificateur PDF/UA pour l’étape de vérification. Cet exemple utilise veraPDF.

Recette

Crée le document.
Appelle enableTaggedPdf() avec une étiquette de langue BCP-47 avant writeHtml(). Le pipeline HTML détecte le mode balisé lorsqu’il construit le parseur et branche l’émetteur de contenu balisé.
Définis les métadonnées du document (titre, langue). setLanguage() reste idempotent par rapport à enableTaggedPdf().
Écris du HTML sémantique. Le parseur associe chaque élément de bloc à un élément de structure : h1 à H1, p à P, ul/li à L/LI, table à Table/TR/TD.
Enregistre, puis valide avec un vérificateur PDF/UA.

Exemple complet

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

Sortie attendue

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

Le fichier produit contient un arbre de structure, /MarkInfo << /Marked true >>, l’entrée /Lang du catalogue et le marqueur XMP pdfuaid:part. Exécute le vérificateur pour confirmer qu’ils sont présents et cohérents entre eux.

Cas limites

Ordre des appels. enableTaggedPdf() après writeHtml() ne balise pas a posteriori le contenu déjà écrit. Active d’abord le mode balisé.
Étiquette de langue. Passe ConformancePolicy::strictUa2() comme deuxième argument pour rejeter une étiquette BCP-47 mal formée à l’entrée de l’API, plutôt que de la supprimer silencieusement au moment de l’écriture.
Réactivation idempotente. Appeler enableTaggedPdf() deux fois met à jour la langue sans reconstruire l’arbre de structure que tu as déjà rempli.
Balisage manuel. Pour du contenu non-HTML, encadre les éléments avec beginTag() / endTag(). Les types conteneurs (Table, THead, TBody, TFoot, TR, L, LI, et les éléments de regroupement Sect/Div/Art/Aside/BlockQuote) deviennent des éléments de regroupement sans contenu marqué ; le contenu en ligne libre placé directement dans un élément de regroupement est encapsulé dans un P synthétisé. Les types feuilles (P, H1–H6, TD, TH) reçoivent des MCID.
La prise en charge n’est pas la conformité. NextPDF émet les métadonnées structurelles dont PDF/UA-2 a besoin. Il remonte aussi un avertissement lorsque la parité est dégradée : pour une validation de production, le recours à un oracle externe relève de la responsabilité de l’appelant. Exécute un vérificateur avant d’affirmer qu’un fichier est conforme.
Les tableaux HTML balisés et les éléments de regroupement passent veraPDF ua2. Un <table> balisé — plat, avec colspan/rowspan, paginé sur plusieurs pages, ou imbriqué dans une cellule — émet la structure Table/TR/TH/TD (ISO 32000-2 §14.8 ; les cellules fusionnées portent les attributs /ColSpan et /RowSpan de la Table 384), et les éléments de regroupement <section>/<div>/<article>/<aside>/<blockquote> émettent une structure de regroupement dont le contenu en ligne libre est encapsulé dans un P synthétisé. veraPDF --flavour ua2 ne signale aucun échec sur ces cas. Un cas échoue encore : un élément de bloc imbriqué dans un élément en ligne — un titre dans un lien, <a><h2>…</h2></a> — déclenche Link shall not contain Hn, garde donc le contenu de bloc hors des enveloppes en ligne. Exécute un vérificateur avant d’affirmer qu’un fichier est conforme.

Conformité

Énoncé	Spécification	Article
Le contenu réel requiert une structure logique.	ISO 14289-2	§8.2.2
Les éléments de structure suivent un ordre d’imbrication et de lecture défini.	ISO 14289-2	§8.2.3

Cette recipe montre comment produire la structure balisée qui sert de base à la création de documents accessibles. Elle n’affirme pas la conformité PDF/UA-2 ; seul un vérificateur la détermine.