Anlamsal içerikten etiketli bir PDF/UA-2 yapı ağacı oluşturun

Genel bakış

Bu tarif, etiketli bir Taşınabilir Belge Biçimi/Evrensel Erişilebilirlik 2 (PDF/UA-2) dosyası oluşturur. Uluslararası Standardizasyon Örgütü (ISO) 14289-2’yi hedef alır. NextPDF; mantıksal yapı ağacı, işaretli içerik dizileri, katalog dili ve belge düzeyinde tanımlama meta verisi üretir. Bu yapı erişilebilir yazarlığı destekler, ancak uygunluk kararını bağımsız bir denetleyici verir. Tarif şu örneği temel alır: examples/31-pdfua2-tagged.php.

Kurulum

composer require nextpdf/core:^3

Doğrulama için PATH’e bir PDF/UA-2 denetleyicisi ekleyin. Bu tarif, ua2 tabanlı veraPDF’yi kullanır. Etiketli yapıyı üretmek için Pro ya da Enterprise paketine ihtiyacınız yoktur.

Kavramsal genel bakış

Etiketli bir PDF, görsel içerik akışına paralel bir mantıksal yapı ağacı taşır. Yardımcı teknoloji, piksel yerleşimi yerine bu ağacı okur; bu nedenle yapı, sunulan okuma sırasını belirler. ISO 14289-2 burada dört gereklilik getirir. Gerçek (yapay olmayan) içeriğe bu ağaç üzerinden erişilebilmelidir (§8.2.2). Yapı öğeleri tanımlı bir düzende iç içe yerleşmelidir (§8.2.3). Her öğe, doğrudan ya da rol eşlemesiyle bilinen bir yapı ad alanına çözümlenmelidir (§8.2.4). İçeriğin doğal dili belge düzeyinde bildirilir ve farklılık gösteren her yapı öğesi için ayrıca belirtilir (§8.4.4).

NextPDF bunu türlenmiş bir ConformanceMode ile modeller. enableTaggedPdf(), ConformanceMode::PdfUa2 değerini ayarlar; bu da (a) Köprü Metni İşaretleme Dili (HTML) ardışık düzeninin ayrıştırıcı oluşturulurken bir TaggedContentEmitter bağlamasını sağlar, (b) etiketli bir PDF’yi belirten katalog MarkInfoMarked bayrağını ayarlar (ISO 32000-2 §14.7) ve (c) katalog Lang girdisi için En İyi Güncel Uygulama 47 (BCP-47) dil etiketini kaydeder. Oluşturucu ayrıca sayfa başına Tabs girdisini üretir; böylece sekme sırası yapı sırasını izler (ISO 32000-2 §14.8).

Katı UA-2 değişmezleri yalnızca ConformanceMode::PdfUa2 için geçerlidir. Tasarım gereği, başka herhangi bir kipe karşı katı bir ConformancePolicy oluşturmak InvalidConfigException fırlatır.

API yüzeyi

Uygulama programlama arayüzü (API) yüzeyi PHPDoc’tan türetilir. Şu ana giriş noktalarını kullanın:

\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 (enableTaggedPdf() tarafından ayarlanan kip)
Document::beginTag(string $type): static / Document::endTag(): static (HTML olmayan içerik için elle etiketleme)

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Bu kendi kendine yeten program test koşum ortamında çalışabilir. Üretimde, hatalı biçimlendirilmiş bir dil etiketini yalnızca harici denetleyici çalıştığında keşfetmek yerine erken aşamada başarısız olacak şekilde davranın. Geçersiz bir BCP-47 etiketini API sınırında reddetmek için ConformancePolicy::strictUa2() iletin, ardından yapıyı denetleyici kararına bağlayın.

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

Beklenen standart çıktı (STDOUT), verapdf --flavour ua2 komutunun uygun bir dosya bildirdiği ana makinede şöyledir:

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

Eğer enableTaggedPdf() dil etiketini reddederse, program standart hataya (STDERR) Tagged PDF/UA-2 setup rejected: … çıktısını yazar ve sıfırdan farklı bir kodla çıkar. Denetleyici bir sorun bildirirse, veraPDF FAILED — output is not PDF/UA-2 conforming çıktısının ardından sıfırdan farklı bir kodla çıkar. Kararı denetleyici verir: NextPDF yapıyı üretir, ancak uygunluk iddiasında bulunmaz.

Sınır durumları ve dikkat edilecekler

Çağrı sırası. enableTaggedPdf() çağrısının writeHtml() sonrasında yapılması, halihazırda yazılmış içeriği geriye dönük olarak etiketlemez. Önce etiketli kipi etkinleştirin.
Katı dil geçidi. İlke olmadan, ayrıştırılamayan bir BCP-47 etiketi sessizce düşürülür ve yalnızca denetleyici çalıştığında görünür. ConformancePolicy::strictUa2() ile aynı etiket InvalidConfigException fırlatır; bu, enableTaggedPdf() sınırında gerçekleşir (ISO 14289-2 §8.4.4 katı yol).
Etkisiz yeniden etkinleştirme. enableTaggedPdf() çağrısını iki kez yaparsanız, NextPDF zaten doldurulmuş bir yapı ağacını yeniden oluşturmadan dili günceller.
Elle etiketleme. HTML olmayan içerik için öğeleri beginTag() / endTag() ile sarmalayın. Kapsayıcı roller (Table, TR, L, LI) işaretli içeriği olmayan gruplama öğeleri haline gelir. Yaprak roller (P, H1–H6, TD) işaretli içerik tanımlayıcıları (MCID’ler) alır.
Kip dışlayıcılığı. Katı bir ConformancePolicy yalnızca ConformanceMode::PdfUa2 ile geçerlidir. Katı UA-2 bayraklarını bir PDF/A kipiyle birleştirmek InvalidConfigException fırlatır. Etiketli bir PDF/A teslimatını, etiketli kipi ve PDF/A profilini ayrı ayrı etkinleştirerek oluşturun.

Başarım

Yapı ağacı, hafif sözlüklerden oluşan paralel bir ağaç ve her metin parçası için BDC/EMC işleçleri ekler. Tipik bir rapor için ek yük, çıktı boyutunun yüzde birkaçıdır ve 2000 ms / 128 MB bütçesinin rahatlıkla içinde kalır. Anlamsal yeniden üretilebilirlik profili geçerlidir, çünkü denetleyici odaklı bir teslimat ham baytlarla değil yapısal soyut sözdizimi ağacı (AST) ve meta veri üzerinden karşılaştırılır. Uygunluk bölümüne bakın.

Güvenlik notları

Veri ikametgâhı ve KKB hafifletmeleri

Yapı ağacı, görünür içerikle aynı metni taşır. Kaynak HTML, kişisel kimlik bilgileri (KKB) dahil kişisel veri içeriyorsa, bu veriye yapı ağacı ve ActualText/Alt öznitelikleri üzerinden de erişilebilir. Görünür içerik için uygulayacağınız aynı redaksiyon ve en aza indirmeyi yazarlıktan önce uygulayın. Etiketleme yeni bir sızdırma yolu eklemez, ancak metni tasarım gereği programatik olarak çıkarılabilir kılar.

Güvenli telemetri ve günlük temizleme

Tarif, STDOUT’a yalnızca sabit bir ilerleme satırı yazar. PDF’yi test koşum ortamının yan kanalına (NEXTPDF_COOKBOOK_OUTPUT) ya da çağıranın verdiği yola yönlendirir. Belge metni asla günlüğe kaydedilmez. İçerik parçalarını yankılayabilen denetleyici çıktısını paylaşılan günlüklerden uzak tutun.

Tehdit modeli

Etiketli bir PDF bir güven sınırı değildir. Tüketiciniz otomatik işleme için yapı ağacına güveniyorsa, dosyayı yine de doğrulamalıdır; çünkü kötü niyetli bir üretici yapısal olarak düzgün biçimlendirilmiş ama yanıltıcı bir ağaç üretebilir. Yapıyı bir bütünlük ya da özgünlük sinyali olarak değil, bir erişilebilirlik olanağı olarak değerlendirin.

FIPS kipi davranışı

Bu tarif hiçbir kriptografik işlem gerçekleştirmez. Federal Bilgi İşleme Standartları (FIPS) kipi davranışını değiştirmez. Hiçbir imzalama ya da şifreleme söz konusu değildir.

PDF/UA-2 eşlemesi

PDF/UA-2 gerekliliği	NextPDF’in ürettiği	Madde
Gerçek içerik yapı ağacında yer alır	`StructTreeRoot` ile blok başına `StructElem` ve MCID’ye bağlı işaretli içerik	ISO 14289-2 §8.2.2
Tanımlı iç içe geçme ve okuma sırası	Belge sırası içinde grouping/leaf rollerine eşlenen blok öğeleri	ISO 14289-2 §8.2.3
Bilinen yapı ad alanı	PDF 2.0 ad alanındaki roller; gerektiğinde rol eşlenen HTML etiketleri	ISO 14289-2 §8.2.4
Belge ve öğe dili	BCP-47 etiketinden katalog `Lang`; öğe başına `Lang`, farklılık gösterdiğinde	ISO 14289-2 §8.4.4
Metin olmayan içeriğin bir metin alternatifi vardır	`Alt`/`ActualText`, figure/non-text yapı öğelerinde taşınır	ISO 14289-2 §8.5.1
Tablo ilişkileri	`Table`/`TR`/`TH`/`TD` rolleri ile başlık ilişkilendirmesi	ISO 14289-2 §8.2.5.26
Bölüm tanımlama meta verisi	Kaydetme sırasında zamanlanan belge düzeyinde tanımlama	ISO 14289-2 §Giriş (`pdfua2#p17`)

Etiket → ISO 32000-2 §14 çapraz başvuru

PDF/UA-2, erişilebilirlik gerekliliklerini ISO 32000-2 etiketli PDF düzeneğinin üzerine katman olarak yerleştirir. NextPDF bu eşlemeye dayanır:

NextPDF üretimi	ISO 32000-2 §14 olanağı	Madde
Mantıksal yapı ağacı (`StructTreeRoot`)	Etiketli PDF mantıksal yapısı	§14.7 (`iso32000_2_sec14#x1.x38.p13`)
Katalog `MarkInfo << /Marked true >>`	Etiketli PDF işaretleyicisi	§14.7 (`iso32000_2_sec14#x1.x40.p3`)
Yapı sırasını izleyen sayfa başına `Tabs` girdisi	Yapısal gezinme / sekme sırası	§14.8 (`iso32000_2_sec14#x1.x50`)

WCAG 2.2 eşlemesi

PDF/UA-2, Web İçeriği Erişilebilirlik Yönergeleri (WCAG) 2.2’nin biçimden bağımsız olarak belirttiği yapı gerekliliklerinin PDF biçimindeki ifadesidir. İlgili eşleme:

WCAG 2.2 başarı ölçütü	Bu tarifin ürettiği PDF/UA-2 mekanizması
1.3.1 Bilgi ve İlişkiler (Düzey A)	Yapı ağacı; başlıkları, listeleri ve tablo ilişkilerini programatik olarak belirlenebilir kılar (`wcag_2_2#x2.x3.x3.x1.p3`).
1.3.2 Anlamlı Sıra (Düzey A)	Yapı sırası, okuma sırasını görsel yerleşimden bağımsız olarak tanımlar.
3.1.1 Sayfa Dili (Düzey A)	BCP-47 etiketinden katalog `Lang` girdisi.
1.1.1 Metin Olmayan İçerik (Düzey A)	`Alt`/`ActualText`, metin olmayan yapı öğelerinde (ISO 14289-2 §8.5.1).

Bu eşleme, üretilen yapının bir WCAG 2.2 ölçütünü nerede desteklediğini gösterir. Bir WCAG uygunluk iddiası değildir. WCAG uygunluğu tüm kullanıcı deneyimini kapsar ve buna üretici değil bir erişilebilirlik değerlendirmesi karar verir.

Uygunluk

İfade	Belirtim	Madde
Gerçek içerik bir mantıksal yapı gerektirir.	ISO 14289-2	§8.2.2
Yapı öğeleri tanımlı bir iç içe geçme ve okuma sırasını izler.	ISO 14289-2	§8.2.3
Her yapı öğesi, doğrudan ya da rol eşlemesiyle bilinen bir ad alanına çözümlenir.	ISO 14289-2	§8.2.4
Doğal dil, belge ve yapı öğesi düzeyinde bildirilir.	ISO 14289-2	§8.4.4
Metin olmayan içerik bir metin alternatifi taşır.	ISO 14289-2	§8.5.1
Tablo hücreleri row/header/veri ilişkilerini taşır.	ISO 14289-2	§8.2.5.26
Etiketli PDF işaretleyicisi, katalog `MarkInfoMarked` bayrağıdır.	ISO 32000-2	§14.7
Uygunluk, üreticinin beyanıyla değil, ilgili bölüme göre belirlenir.	ISO 14289-2	§8.14.2

NextPDF, erişilebilir yazarlığı destekleyen etiketli yapıyı üretir. Destek, uygunluk değildir. Bu tarif PDF/UA-2 uygunluğu iddiasında bulunmaz. Bu kararı veraPDF gibi bağımsız bir denetleyici verir. Bir dosyanın uygun olduğunu söylemeden önce denetleyiciyi çalıştırın.