Getaggten PDF/UA-2-Strukturbaum aus semantischem Inhalt ausgeben

Auf einen Blick

Dieses Recipe erzeugt ein getaggtes PDF, das auf ISO 14289-2 (PDF/UA-2) ausgerichtet ist. NextPDF gibt einen logischen Strukturbaum, Marked-Content-Sequenzen, die Katalogsprache und die dokumentweiten Identifikationsmetadaten aus. Diese Struktur unterstützt barrierefreies Authoring; die Konformitätsentscheidung trifft jedoch ein unabhängiges Prüfwerkzeug. Das Recipe folgt examples/31-pdfua2-tagged.php.

Installation

composer require nextpdf/core:^3

Der Verifizierungsschritt erfordert ein PDF/UA-2-Prüfwerkzeug im PATH. Die Beispiele in diesem Recipe verwenden veraPDF mit dem ua2-Flavour. Sie benötigen kein Pro- oder Enterprise-Paket, um die getaggte Struktur auszugeben.

Konzeptioneller Überblick

Ein getaggtes PDF führt neben dem visuellen Inhaltsstrom einen parallelen logischen Strukturbaum. Assistive Technologien lesen diesen Baum, nicht das Pixel-Layout; daher bestimmt die Struktur die nach außen sichtbare Lesereihenfolge. ISO 14289-2 stellt hierfür vier Anforderungen. Echter (nicht als Artefakt markierter) Inhalt muss über diesen Baum erreichbar sein (§8.2.2). Strukturelemente müssen in einer definierten Reihenfolge verschachtelt sein (§8.2.3). Jedes Element muss sich auf einen bekannten Strukturnamensraum auflösen, entweder direkt oder per Role-Mapping (§8.2.4). Die natürliche Sprache des Inhalts wird auf Dokumentebene deklariert und je Strukturelement verfeinert, wenn sie abweicht (§8.4.4).

NextPDF modelliert dies mit einem typisierten ConformanceMode. enableTaggedPdf() setzt ConformanceMode::PdfUa2; dadurch wird (a) die HTML-Pipeline beim Erzeugen des Parsers so konfiguriert, dass sie einen TaggedContentEmitter verdrahtet, (b) das Katalog-Flag MarkInfoMarked gesetzt, das ein getaggtes PDF signalisiert (ISO 32000-2 §14.7), und (c) die BCP-47-Sprache für den Katalogeintrag Lang gespeichert. Der Writer gibt außerdem den seitenbezogenen Eintrag Tabs aus, damit die Tabulatorreihenfolge der Strukturreihenfolge folgt (ISO 32000-2 §14.8).

Die strengen UA-2-Invarianten gelten ausschließlich für ConformanceMode::PdfUa2. Wird eine strenge ConformancePolicy für einen anderen Modus konstruiert, löst dies absichtlich InvalidConfigException aus.

API-Oberfläche

Die API-Oberfläche wird aus PHPDoc generiert. Die wichtigsten Einstiegspunkte sind:

\NextPDF\Core\Document::createStandalone(): Document
Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static
Document::setLanguage(string $lang): static
\NextPDF\Conformance\ConformancePolicy::strictUa2(): self
\NextPDF\Conformance\ConformanceMode::PdfUa2 (der von enableTaggedPdf() gesetzte Modus)
Document::beginTag(string $type): static / Document::endTag(): static (manuelles Tagging für Nicht-HTML-Inhalt)

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// Enable tagged mode BEFORE writeHtml(). The HTML pipeline detects the
// mode at parser construction time and wires the tagged-content emitter.
$doc->enableTaggedPdf(lang: 'en');

$doc->setTitle('Quarterly Accessibility Report');
$doc->setLanguage('en');
$doc->addPage();

$doc->writeHtml(<<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML);

$doc->save(__DIR__ . '/output/31-pdfua2-tagged.pdf');

echo "Created: output/31-pdfua2-tagged.pdf\n";

Codebeispiel — Produktion

Dies ist das eigenständige, vom Harness ausführbare Programm. In einer Produktionsintegration sollte ein fehlerhaftes Sprach-Tag früh scheitern, statt erst beim Lauf des externen Prüfwerkzeugs aufzufallen. Übergeben Sie ConformancePolicy::strictUa2(), um ein ungültiges BCP-47-Tag an der API-Grenze abzulehnen, und machen Sie den Build anschließend vom Urteil des Prüfwerkzeugs abhängig.

<?php

declare(strict_types=1);

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

use NextPDF\Conformance\ConformancePolicy;
use NextPDF\Core\Document;
use NextPDF\Exception\InvalidConfigException;

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: (__DIR__ . '/accessible.pdf');

try {
    $doc = Document::createStandalone();

    // Strict UA-2: a malformed BCP 47 tag throws here, not silently at
    // write time. strictUa2() also forces the §8.4.4 Lang validation.
    $doc->enableTaggedPdf(lang: 'en-GB', policy: ConformancePolicy::strictUa2());

    $doc->setTitle('Accessible Annual Report 2026');
    $doc->setLanguage('en-GB');
    $doc->addPage();

    $doc->writeHtml(<<<'HTML'
<h1>Annual Report 2026</h1>
<p>Audited results for the financial year ending March 2026.</p>
<h2>Segment performance</h2>
<table>
  <tr><th>Segment</th><th>Revenue</th></tr>
  <tr><td>Cloud</td><td>42.1</td></tr>
  <tr><td>Services</td><td>18.7</td></tr>
</table>
HTML);

    $doc->save($out);
} catch (InvalidConfigException $e) {
    fwrite(STDERR, "Tagged PDF/UA-2 setup rejected: {$e->getMessage()}\n");
    exit(1);
}

// The gate is the checker, not the library.
$exitCode = 0;
$report = [];
exec('verapdf --flavour ua2 ' . escapeshellarg($out), $report, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "veraPDF FAILED — output is not PDF/UA-2 conforming\n");
    fwrite(STDERR, implode("\n", $report) . "\n");
    exit(1);
}

echo "veraPDF PASS — accessible.pdf carries a conforming UA-2 structure\n";

Erwartete STDOUT-Ausgabe auf einem Host, auf dem verapdf --flavour ua2 die Datei als konform meldet:

veraPDF PASS — accessible.pdf carries a conforming UA-2 structure

Wenn enableTaggedPdf() das Sprach-Tag ablehnt, beendet sich das Programm mit einem Wert ungleich null, nachdem es Tagged PDF/UA-2 setup rejected: … auf STDERR ausgegeben hat. Meldet das Prüfwerkzeug ein Problem, beendet sich das Programm mit einem Wert ungleich null nach veraPDF FAILED — output is not PDF/UA-2 conforming. Die Entscheidung trifft das Prüfwerkzeug: NextPDF gibt die Struktur aus, behauptet aber keine Konformität.

Randfälle & Fallstricke

Aufrufreihenfolge. enableTaggedPdf() nach writeHtml() taggt bereits geschriebenen Inhalt nicht nachträglich. Aktivieren Sie den getaggten Modus zuerst.
Strenges Sprach-Gate. Ohne Policy wird ein nicht parsebares BCP-47-Tag stillschweigend verworfen und fällt erst beim Lauf des Prüfwerkzeugs auf. Mit ConformancePolicy::strictUa2() löst dasselbe Tag an der Grenze von enableTaggedPdf() eine InvalidConfigException aus (ISO 14289-2 §8.4.4 strikter Pfad).
Idempotentes erneutes Aktivieren. Ein zweiter Aufruf von enableTaggedPdf() aktualisiert die Sprache, ohne einen bereits befüllten Strukturbaum neu aufzubauen.
Manuelles Tagging. Bei Nicht-HTML-Inhalt umschließen Sie Elemente mit beginTag() / endTag(). Container-Rollen (Table, TR, L, LI) werden zu Gruppierungselementen ohne Marked Content. Blatt-Rollen (P, H1–H6, TD) erhalten MCIDs.
Modus-Exklusivität. Eine strenge ConformancePolicy ist nur mit ConformanceMode::PdfUa2 gültig. Die Kombination strenger UA-2-Flags mit einem PDF/A-Modus löst InvalidConfigException aus. Erstellen Sie ein getaggtes PDF/A-Deliverable, indem Sie den getaggten Modus und das PDF/A-Profil getrennt aktivieren.

Performance

Der Strukturbaum ergänzt einen parallelen Baum aus leichtgewichtigen Dictionaries sowie pro Text-Run die Operatoren BDC/EMC. Bei einem typischen Report liegt der Overhead bei wenigen Prozent der Ausgabegröße und bleibt deutlich im Budget von 2000 ms / 128 MB. Das Profil der semantischen Reproduzierbarkeit greift hier, weil ein für das Prüfwerkzeug bestimmtes Deliverable über den strukturellen abstrakten Syntaxbaum (AST) plus Metadaten verglichen wird, nicht über die rohen Bytes. Siehe den Abschnitt Konformität.

Sicherheitshinweise

Datenresidenz & PII-Schutzmaßnahmen

Der Strukturbaum trägt denselben Text wie der sichtbare Inhalt. Enthält das Quell-HTML personenbezogene Daten, sind diese Daten auch über den Baum sowie über die Attribute ActualText/Alt erreichbar. Wenden Sie vor dem Authoring dieselbe Schwärzung und Minimierung an wie für den sichtbaren Inhalt. Tagging fügt keinen neuen Exfiltrationspfad hinzu, macht den Text aber per Design programmatisch extrahierbar.

Sichere Telemetrie & Log-Bereinigung

Das Recipe schreibt nur eine feste Fortschrittszeile nach STDOUT. Es leitet das PDF an den Seitenkanal des Harness (NEXTPDF_COOKBOOK_OUTPUT) oder an einen vom Aufrufer angegebenen Pfad. Dokumenttext wird niemals geloggt. Halten Sie die Ausgabe des Prüfwerkzeugs, die Inhaltsfragmente wiedergeben kann, aus gemeinsam genutzten Logs heraus.

Bedrohungsmodell

Ein getaggtes PDF ist keine Vertrauensgrenze. Ein Consumer, der dem Strukturbaum für die automatisierte Verarbeitung vertraut, muss die Datei trotzdem validieren, weil ein böswilliger Erzeuger einen strukturell wohlgeformten, aber irreführenden Baum ausgeben kann. Behandeln Sie die Struktur als Hilfsmittel für Barrierefreiheit, nicht als Integritäts- oder Authentizitätssignal.

Verhalten im FIPS-Modus

Dieses Recipe führt keine kryptografischen Operationen aus. Der FIPS-Modus ändert sein Verhalten nicht. Es ist keine Signierung oder Verschlüsselung beteiligt.

PDF/UA-2-Zuordnung

PDF/UA-2-Anforderung	Was NextPDF ausgibt	Klausel
Echter Inhalt liegt im Strukturbaum	`StructTreeRoot` mit blockweisem `StructElem` und MCID-verknüpftem Marked Content	ISO 14289-2 §8.2.2
Definierte Verschachtelung und Lesereihenfolge	Blockelemente in Dokumentreihenfolge auf grouping/leaf-Rollen abgebildet	ISO 14289-2 §8.2.3
Bekannter Strukturnamensraum	Rollen im PDF 2.0-Namensraum; HTML-Tags bei Bedarf per Role-Mapping	ISO 14289-2 §8.2.4
Dokument- und Elementsprache	Katalog-`Lang` aus dem BCP-47-Tag; `Lang` je Element, wenn es abweicht	ISO 14289-2 §8.4.4
Nicht-Text-Inhalt hat eine Textalternative	`Alt`/`ActualText` auf figure/non-text-Strukturelementen getragen	ISO 14289-2 §8.5.1
Tabellenbeziehungen	`Table`/`TR`/`TH`/`TD`-Rollen mit Header-Zuordnung	ISO 14289-2 §8.2.5.26
Metadaten zur Teilidentifikation	Dokumentweite Identifikation, beim Speichern abgeschlossen	ISO 14289-2 §Intro (`pdfua2#p17`)

Tag → ISO 32000-2 §14-Querverweis

PDF/UA-2 definiert Barrierefreiheitsanforderungen auf Basis der Tagged-PDF-Mechanismen von ISO 32000-2. Die Zuordnung, auf die sich NextPDF stützt:

NextPDF-Ausgabe	ISO 32000-2 §14-Funktion	Klausel
Logischer Strukturbaum (`StructTreeRoot`)	Logische Struktur des getaggten PDF	§14.7 (`iso32000_2_sec14#x1.x38.p13`)
Katalog-`MarkInfo << /Marked true >>`	Getaggte-PDF-Marker	§14.7 (`iso32000_2_sec14#x1.x40.p3`)
Seitenbezogener `Tabs`-Eintrag, der der Strukturreihenfolge folgt	Strukturelle Navigation / Tabulatorreihenfolge	§14.8 (`iso32000_2_sec14#x1.x50`)

WCAG 2.2-Zuordnung

PDF/UA-2 ist der PDF-Format-Ausdruck von Strukturanforderungen, die WCAG 2.2 formatunabhängig formuliert. Die relevante Zuordnung lautet:

WCAG 2.2-Erfolgskriterium	PDF/UA-2-Mechanismus, den dieses Recipe erzeugt
1.3.1 Info und Beziehungen (Stufe A)	Der Strukturbaum macht Überschriften, Listen und Tabellenbeziehungen programmatisch ermittelbar (`wcag_2_2#x2.x3.x3.x1.p3`).
1.3.2 Bedeutungstragende Reihenfolge (Stufe A)	Die Strukturreihenfolge definiert die Lesereihenfolge unabhängig vom visuellen Layout.
3.1.1 Sprache der Seite (Stufe A)	Der Katalogeintrag `Lang` wird aus dem BCP-47-Tag gesetzt.
1.1.1 Nicht-Text-Inhalt (Stufe A)	`Alt`/`ActualText` auf Nicht-Text-Strukturelementen (ISO 14289-2 §8.5.1).

Diese Zuordnung zeigt, wo die ausgegebene Struktur ein WCAG 2.2-Kriterium unterstützt. Sie ist keine WCAG-Konformitätsaussage. WCAG-Konformität deckt die gesamte Benutzererfahrung ab und wird durch eine Barrierefreiheitsbewertung bestimmt, nicht durch den Erzeuger.

Konformität

Aussage	Spezifikation	Klausel
Echter Inhalt erfordert eine logische Struktur.	ISO 14289-2	§8.2.2
Strukturelemente folgen einer definierten Verschachtelung und Lesereihenfolge.	ISO 14289-2	§8.2.3
Jedes Strukturelement ist direkt oder per Role-Mapping einem bekannten Namensraum zugeordnet.	ISO 14289-2	§8.2.4
Die natürliche Sprache wird auf Dokument- und Strukturelementebene deklariert.	ISO 14289-2	§8.4.4
Nicht-Text-Inhalt trägt eine Textalternative.	ISO 14289-2	§8.5.1
Tabellenzellen führen row/header/Daten-Beziehungen.	ISO 14289-2	§8.2.5.26
Der Marker für getaggte PDF ist das Katalog-Flag `MarkInfoMarked`.	ISO 32000-2	§14.7
Konformität wird gegen den Teil entschieden, nicht vom Erzeuger behauptet.	ISO 14289-2	§8.14.2

NextPDF gibt die getaggte Struktur aus, die barrierefreies Authoring unterstützt. Unterstützung ist keine Konformität. Dieses Recipe behauptet keine PDF/UA-2-Konformität. Diese Entscheidung trifft ein unabhängiges Prüfwerkzeug (zum Beispiel veraPDF). Lassen Sie das Prüfwerkzeug laufen, bevor Sie erklären, dass eine Datei konform ist.