Hasilkan pohon struktur PDF/UA-2 bertag dari konten semantik

Sekilas pandang

Resep ini membuat berkas Portable Document Format/Universal Accessibility 2 (PDF/UA-2) bertag yang menyasar International Organization for Standardization (ISO) 14289-2. NextPDF menghasilkan pohon struktur logis, urutan marked-content, bahasa katalog, dan metadata identifikasi tingkat dokumen. Struktur ini mendukung penulisan yang aksesibel, tetapi kesesuaian tetap ditentukan oleh pemeriksa independen. Resep ini mengikuti examples/31-pdfua2-tagged.php.

Pemasangan

composer require nextpdf/core:^3

Letakkan pemeriksa PDF/UA-2 di PATH untuk verifikasi. Resep ini menggunakan veraPDF dengan flavour ua2. Anda tidak memerlukan paket Pro atau Enterprise untuk menghasilkan struktur bertag.

Gambaran konseptual

PDF bertag memuat pohon struktur logis yang berjalan paralel dengan aliran konten visual. Teknologi bantu membaca pohon ini, bukan tata letak pikselnya, sehingga struktur itulah yang menentukan urutan baca yang terekspos. ISO 14289-2 menetapkan empat persyaratan yang relevan di sini. Konten nyata (bukan artifact) harus dapat dijangkau melalui pohon tersebut (§8.2.2). Elemen struktur harus tersarang dalam urutan yang ditentukan (§8.2.3). Setiap elemen harus berada dalam namespace struktur yang dikenal, baik secara langsung maupun melalui pemetaan peran (§8.2.4). Bahasa alami konten dideklarasikan pada tingkat dokumen dan diperinci per elemen struktur jika berbeda (§8.4.4).

NextPDF memodelkan hal ini dengan ConformanceMode. enableTaggedPdf() menetapkan ConformanceMode::PdfUa2, yang (a) membuat pipeline Hypertext Markup Language (HTML) menghubungkan sebuah TaggedContentEmitter saat parser dikonstruksi, (b) menetapkan flag katalog MarkInfoMarked yang menandakan PDF bertag (ISO 32000-2 §14.7), dan (c) mencatat bahasa Best Current Practice 47 (BCP 47) untuk entri katalog Lang. NextPDF juga menghasilkan entri Tabs per halaman, sehingga urutan tab mengikuti urutan struktur (ISO 32000-2 §14.8).

Invarian ketat UA-2 hanya berlaku untuk ConformanceMode::PdfUa2. Secara desain, membuat ConformancePolicy ketat untuk mode lain apa pun akan melempar InvalidConfigException.

Permukaan API

Permukaan application programming interface (API) ini berasal dari PHPDoc. Gunakan titik masuk utama berikut:

\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 (mode yang ditetapkan oleh enableTaggedPdf())
Document::beginTag(string $type): static / Document::endTag(): static (penandaan manual untuk konten non-HTML)

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Program mandiri ini dapat berjalan di dalam harness. Di lingkungan produksi, buat proses gagal lebih awal saat tag bahasa cacat, alih-alih baru menemukannya ketika pemeriksa eksternal berjalan. Teruskan ConformancePolicy::strictUa2() untuk menolak tag BCP 47 yang tidak valid di batas API, lalu jadikan vonis pemeriksa sebagai gerbang build.

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

Di host tempat verapdf --flavour ua2 melaporkan berkas sebagai sesuai, standard output (STDOUT) yang diharapkan adalah:

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

Jika enableTaggedPdf() menolak tag bahasa, program keluar dengan kode bukan nol setelah menulis Tagged PDF/UA-2 setup rejected: … ke standard error (STDERR). Jika pemeriksa melaporkan masalah, program keluar dengan kode bukan nol setelah veraPDF FAILED — output is not PDF/UA-2 conforming. Pemeriksalah yang memberi vonis: NextPDF menghasilkan strukturnya, tetapi tidak menyatakan kesesuaian.

Kasus tepi & jebakan

Urutan pemanggilan. enableTaggedPdf() setelah writeHtml() tidak menandai secara surut konten yang sudah ditulis. Aktifkan mode bertag terlebih dahulu.
Gerbang bahasa ketat. Tanpa kebijakan, tag BCP 47 yang tidak dapat diuraikan akan dibuang secara diam-diam dan baru terdeteksi saat pemeriksaan. Dengan ConformancePolicy::strictUa2(), tag yang sama akan melempar InvalidConfigException di batas enableTaggedPdf() (ISO 14289-2 §8.4.4 jalur ketat).
Pengaktifan ulang yang idempoten. Jika Anda memanggil enableTaggedPdf() dua kali, NextPDF memperbarui bahasanya tanpa membangun ulang pohon struktur yang sudah terisi.
Penandaan manual. Untuk konten non-HTML, bungkus item dengan beginTag() / endTag(). Peran kontainer (Table, TR, L, LI) menjadi elemen pengelompokan tanpa marked content. Peran daun (P, H1–H6, TD) memperoleh marked-content identifier (MCID).
Eksklusivitas mode. Sebuah ConformancePolicy ketat hanya valid dengan ConformanceMode::PdfUa2. Menggabungkan flag UA-2 ketat dengan mode PDF/A akan melempar InvalidConfigException. Untuk membuat keluaran PDF/A bertag, aktifkan mode bertag dan profil PDF/A secara terpisah.

Performa

Pohon struktur menambahkan pohon paralel yang berisi kamus ringan serta operator BDC/EMC per text-run. Untuk laporan pada umumnya, overhead-nya hanya beberapa persen dari ukuran keluaran dan tetap jauh di bawah anggaran 2000 ms / 128 MB. Profil reproduktibilitas semantik berlaku karena keluaran yang berorientasi pemeriksa dibandingkan berdasarkan abstract syntax tree (AST) struktural ditambah metadata, bukan berdasarkan byte mentah. Lihat bagian Kesesuaian.

Catatan keamanan

Residensi Data & Mitigasi PII

Pohon struktur membawa teks yang sama dengan konten yang terlihat. Jika HTML sumber memuat data pribadi, termasuk personally identifiable information (PII), data tersebut juga dapat dijangkau melalui pohon dan melalui atribut ActualText/Alt. Terapkan redaksi dan minimisasi yang sama sebelum penulisan seperti yang Anda lakukan untuk konten yang terlihat. Penandaan tidak menambahkan jalur eksfiltrasi baru, tetapi secara desain membuat teks dapat diekstraksi secara programatis.

Telemetri Aman & Pembersihan Log

Resep ini hanya menulis satu baris progres tetap ke STDOUT. PDF dirutekan ke kanal samping harness (NEXTPDF_COOKBOOK_OUTPUT) atau ke path pemanggil. Teks dokumen tidak pernah dicatat ke log. Jauhkan keluaran pemeriksa, yang dapat menggemakan cuplikan konten, dari log bersama.

Model ancaman

PDF bertag bukan batas kepercayaan. Jika konsumen Anda memercayai pohon struktur untuk pemrosesan otomatis, konsumen tetap harus memvalidasi berkas karena produsen berniat jahat dapat menghasilkan pohon yang secara struktural terbentuk baik tetapi menyesatkan. Perlakukan struktur sebagai sarana aksesibilitas, bukan sebagai sinyal integritas atau keautentikan.

Perilaku mode FIPS

Resep ini tidak melakukan operasi kriptografis apa pun. Mode Federal Information Processing Standards (FIPS) tidak mengubah perilakunya. Tidak ada penandatanganan atau enkripsi yang terlibat.

Pemetaan PDF/UA-2

Persyaratan PDF/UA-2	Yang dihasilkan NextPDF	Klausa
Konten nyata berada di dalam pohon struktur	`StructTreeRoot` dengan `StructElem` per blok dan marked content yang tertaut MCID	ISO 14289-2 §8.2.2
Penyarangan dan urutan baca yang terdefinisi	Elemen blok dipetakan ke peran grouping/leaf dalam urutan dokumen	ISO 14289-2 §8.2.3
Namespace struktur yang dikenal	Peran dalam namespace PDF 2.0; tag HTML dipetakan-peran jika diperlukan	ISO 14289-2 §8.2.4
Bahasa dokumen dan elemen	Katalog `Lang` dari tag BCP 47; `Lang` per elemen jika berbeda	ISO 14289-2 §8.4.4
Konten non-teks memiliki alternatif teks	`Alt`/`ActualText` dibawa pada elemen struktur figure/non-text	ISO 14289-2 §8.5.1
Relasi tabel	`Table`/`TR`/`TH`/`TD` dengan asosiasi header	ISO 14289-2 §8.2.5.26
Metadata identifikasi part	Identifikasi tingkat dokumen dijadwalkan saat penyimpanan	ISO 14289-2 §Intro (`pdfua2#p17`)

Tag → ISO 32000-2 §14 referensi-silang

PDF/UA-2 melapiskan persyaratan aksesibilitas di atas mekanisme PDF bertag ISO 32000-2. NextPDF mengandalkan pemetaan ini:

NextPDF menghasilkan	ISO 32000-2 fasilitas §14	Klausa
Pohon struktur logis (`StructTreeRoot`)	Struktur logis PDF bertag	§14.7 (`iso32000_2_sec14#x1.x38.p13`)
Katalog `MarkInfo << /Marked true >>`	Penanda PDF bertag	§14.7 (`iso32000_2_sec14#x1.x40.p3`)
Entri `Tabs` per halaman mengikuti urutan struktur	Navigasi struktural / urutan tab	§14.8 (`iso32000_2_sec14#x1.x50`)

Pemetaan WCAG 2.2

PDF/UA-2 adalah perwujudan dalam format PDF dari persyaratan struktur yang dinyatakan Web Content Accessibility Guidelines (WCAG) 2.2 tanpa terikat format. Penyelarasan yang relevan:

Kriteria keberhasilan WCAG 2.2	Mekanisme PDF/UA-2 yang dihasilkan resep ini
1.3.1 Info dan Relasi (Level A)	Pohon struktur membuat heading, daftar, dan relasi tabel dapat ditentukan secara programatis (`wcag_2_2#x2.x3.x3.x1.p3`).
1.3.2 Urutan yang Bermakna (Level A)	Urutan struktur menentukan urutan baca terlepas dari tata letak visual.
3.1.1 Bahasa Halaman (Level A)	Entri katalog `Lang` dari tag BCP 47.
1.1.1 Konten Non-teks (Level A)	`Alt`/`ActualText` pada elemen struktur non-teks (ISO 14289-2 §8.5.1).

Pemetaan ini menunjukkan di mana struktur yang dihasilkan mendukung kriteria WCAG 2.2 tertentu. Ini bukan klaim kesesuaian WCAG. Kesesuaian WCAG mencakup keseluruhan pengalaman pengguna, dan ditentukan oleh evaluasi aksesibilitas, bukan oleh produsen.

Kesesuaian

Pernyataan	Spesifikasi	Klausa
Konten nyata memerlukan struktur logis.	ISO 14289-2	§8.2.2
Elemen struktur mengikuti penyarangan dan urutan baca yang terdefinisi.	ISO 14289-2	§8.2.3
Setiap elemen struktur berada dalam namespace yang dikenal, secara langsung atau melalui pemetaan peran.	ISO 14289-2	§8.2.4
Bahasa alami dideklarasikan pada tingkat dokumen dan elemen struktur.	ISO 14289-2	§8.4.4
Konten non-teks membawa alternatif teks.	ISO 14289-2	§8.5.1
Sel tabel membawa relasi row/header/data.	ISO 14289-2	§8.2.5.26
Penanda PDF bertag adalah flag katalog `MarkInfoMarked`.	ISO 32000-2	§14.7
Kesesuaian diputuskan terhadap part, bukan dinyatakan oleh produsen.	ISO 14289-2	§8.14.2

NextPDF menghasilkan struktur bertag yang mendukung penulisan aksesibel. Dukungan bukanlah kesesuaian. Resep ini tidak menyatakan kesesuaian PDF/UA-2. Pemeriksa independen, seperti veraPDF, yang menentukan hal itu. Jalankan pemeriksa sebelum Anda menyatakan sebuah berkas sesuai.