E016_pdfua1.php

<?php

declare(strict_types=1);

/**
 * E016_pdfua1.php
 *
 * Demonstrates HTML auto-tagging in 'pdfua1' (PDF/UA-1, ISO 14289-1) mode.
 *
 * PDF/UA-1 is the original accessible-PDF profile, standardised as ISO 14289-1:2012
 * and built on PDF 1.7.  When this mode is active, tc-lib-pdf:
 *   - Writes StructTreeRoot, ParentTree, and MarkInfo /Marked true
 *   - Forces ViewerPreferences /DisplayDocTitle true
 *   - Sets /Lang from the document language (default en-US)
 *   - Clamps heading levels to prevent skipped H1-H6 levels
 *   - Emits ActualText for ligatures and special glyphs
 *
 * Every HTML element rendered by addHTMLCell() is automatically mapped to the
 * corresponding PDF structure role - no beginStructElem() calls required.
 * Compare with E063 which builds the same structure tree manually.
 *
 * Auto-tagged roles exercised here:
 *   h1-h3       → H1-H3     (heading hierarchy)
 *   p           → P         (paragraph)
 *   blockquote  → BlockQuote
 *   pre         → Code
 *   ul / ol     → L         (list; li → LI > Lbl + LBody auto-generated)
 *   figure      → Figure
 *   img[alt]    → Figure + /Alt (alt text written to struct-elem dictionary)
 *   figcaption  → Caption
 *   table       → Table     (tr → TR, th → TH, td → TD, caption → Caption)
 *   a           → Link
 *
 * @since       2026-04-25
 * @category    Library
 * @package     Pdf
 * @author      Nicola Asuni <info@tecnick.com>
 * @copyright   2002-2026 Nicola Asuni - Tecnick.com LTD
 * @license     https://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE)
 * @link        https://github.com/tecnickcom/tc-lib-pdf
 *
 * This file is part of tc-lib-pdf software library.
 */

// NOTE: local file reads (images, fonts, attachments) are restricted to an allowlist of
// trusted paths that covers this package tree, so run the examples in place. To read assets
// from other locations, list them in the 'allowedPaths' entry of the fileOptions constructor
// parameter (see E047_remote_resources_security.php).

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

\define('K_PATH_FONTS', \realpath(__DIR__ . '/../vendor/tecnickcom/tc-lib-pdf-font/target/fonts'));

$pdf = new \Com\Tecnick\Pdf\Tcpdf(
    unit: \Com\Tecnick\Pdf\Page\Unit::Millimeter,
    isunicode: true,
    subsetfont: false,
    compress: true,
    mode: \Com\Tecnick\Pdf\PdfConformance::Pdfua1,
);
$pdf->setCreator('tc-lib-pdf');
$pdf->setAuthor('Nicola Asuni');
$pdf->setTitle('PDF/UA-1 Auto-Tagged HTML');
$pdf->setSubject('tc-lib-pdf example: 016 — pdfua1 mode HTML tagging showcase');
$pdf->setKeywords('TCPDF tc-lib-pdf pdfua1 PDF/UA-1 ISO14289 tagged PDF accessibility HTML auto-tag');
$pdf->setPDFFilename('E016_pdfua1.pdf');
$pdf->setLanguage(code: 'en-US');

$font = $pdf->font->insert($pdf->pon, 'dejavusans', '', 10);

// PDF/UA requires every font to be embedded. <code>/<pre> default to the
// non-embedded standard-14 Courier, so register an embedded monospace font and
// select it for those elements.
$pdf->font->insert($pdf->pon, 'dejavusansmono', '', 10);
$pdf->setHTMLMonospaceFont('dejavusansmono');

$pdf->addPage();
$pdf->page->addContent($font['out']);

$imgPath = __DIR__ . '/images/tcpdf_logo.jpg';

$html =
    '<h1>PDF/UA-1 — Auto-Tagged HTML Showcase</h1>'
    . '<p>Mode: <strong>pdfua1</strong> (ISO&#160;14289-1, PDF&#160;1.7). This document'
    . ' demonstrates every HTML element that <code>addHTMLCell()</code> auto-tags with a'
    . ' PDF/UA-1 structure role. PDF/UA-1 is the original accessible-PDF standard: it mandates'
    . ' a tagged structure tree, document language, <code>MarkInfo /Marked true</code>,'
    . ' and <code>ViewerPreferences /DisplayDocTitle true</code>. All of these are written'
    . ' automatically when the <em>pdfua1</em> mode is active.</p>'
    . '<h2>1 — Heading and Paragraph Roles</h2>'
    . '<h3>H3 Sub-heading</h3>'
    . '<p>The <code>h1</code>-<code>h6</code> tags map to PDF roles <strong>H1-H6</strong>.'
    . ' The <code>p</code> tag maps to <strong>P</strong>.'
    . ' PDF/UA-1 requires that heading levels are not skipped: the library clamps each'
    . ' heading to at most one level deeper than the previous heading to maintain a'
    . ' well-formed outline that screen readers can navigate.</p>'
    . '<h2>2 — Block Roles</h2>'
    . '<blockquote>&ldquo;Tagged PDF is the foundation of accessible PDF. Without a'
    . ' well-formed structure tree, automated tools and assistive technologies cannot'
    . ' reliably interpret document content.&rdquo; &mdash; ISO&#160;14289-1 rationale</blockquote>'
    . '<p>The <code>blockquote</code> tag maps to <strong>BlockQuote</strong>.</p>'
    . '<h2>3 — List Structure (L &gt; LI &gt; Lbl + LBody)</h2>'
    . '<p>Both <code>ul</code> and <code>ol</code> map to the <strong>L</strong> role.'
    . ' Each <code>li</code> auto-generates <strong>LI &gt; {Lbl, LBody}</strong> children:</p>'
    . '<ul>'
    . '<li>Unordered item &mdash; <code>ul</code>/<code>li</code> tags produce L/LI structure</li>'
    . '<li>The bullet character is placed in a <strong>Lbl</strong> child element</li>'
    . '<li>Body text is wrapped in a <strong>LBody</strong> child element</li>'
    . '</ul>'
    . '<ol>'
    . '<li>Ordered item &mdash; the number is auto-generated as the <strong>Lbl</strong></li>'
    . '<li>Body text is again auto-wrapped in <strong>LBody</strong></li>'
    . '<li>Nesting: L &gt; LI &gt; {Lbl, LBody}</li>'
    . '</ol>'
    . '<h2>4 — Figure, Image Alt-Text, and Caption</h2>'
    . '<figure>'
    . '<img src="'
    . $imgPath
    . '" alt="TCPDF logo: blue text on white background" width="89" height="30" />'
    . '<figcaption>Figure 1 &mdash; TCPDF logo. The <code>alt</code> attribute becomes'
    . ' <strong>/Alt</strong> in the Figure structure-element dictionary.'
    . ' PDF/UA-1 requires every Figure to carry an /Alt or /ActualText entry so'
    . ' screen readers can describe non-text content. The <code>figcaption</code> tag'
    . ' maps to <strong>Caption</strong>.</figcaption>'
    . '</figure>'
    . '<p>A decorative image has an empty <code>alt</code> attribute: it is emitted as an'
    . ' <strong>Artifact</strong>, not as a Figure, so assistive technology skips it:</p>'
    . '<img src="'
    . $imgPath
    . '" alt="" width="45" height="15" />'
    . '<h2>5 — Table Structure (Table &gt; TR &gt; TH/TD)</h2>'
    . '<table border="1" cellspacing="0" cellpadding="3">'
    . '<caption>Table 1 &mdash; HTML tags and their PDF/UA-1 structure roles</caption>'
    . '<tr><th>HTML tag</th><th>PDF structure role</th><th>Category</th></tr>'
    . '<tr><td>h1&ndash;h6</td><td>H1&ndash;H6</td><td>Heading</td></tr>'
    . '<tr><td>p</td><td>P</td><td>Body</td></tr>'
    . '<tr><td>blockquote</td><td>BlockQuote</td><td>Body</td></tr>'
    . '<tr><td>pre</td><td>Code</td><td>Body</td></tr>'
    . '<tr><td>ul, ol</td><td>L</td><td>List</td></tr>'
    . '<tr><td>li</td><td>LI + Lbl + LBody</td><td>List</td></tr>'
    . '<tr><td>figure</td><td>Figure</td><td>Illustration</td></tr>'
    . '<tr><td>img (with alt)</td><td>Figure + /Alt</td><td>Illustration</td></tr>'
    . '<tr><td>img (alt="")</td><td>Artifact</td><td>Decoration</td></tr>'
    . '<tr><td>figcaption, caption</td><td>Caption</td><td>Illustration</td></tr>'
    . '<tr><td>table</td><td>Table</td><td>Table</td></tr>'
    . '<tr><td>tr</td><td>TR</td><td>Table</td></tr>'
    . '<tr><td>td</td><td>TD</td><td>Table</td></tr>'
    . '<tr><td>th</td><td>TH</td><td>Table</td></tr>'
    . '<tr><td>a</td><td>Link</td><td>Inline</td></tr>'
    . '</table>'
    . '<h2>6 — Hyperlink (Link Role)</h2>'
    . '<p>This sentence contains a'
    . ' <a href="https://github.com/tecnickcom/tc-lib-pdf" style="text-decoration:none;">hyperlink to the tc-lib-pdf repository</a>;'
    . ' the <code>a</code> element is tagged with the <strong>Link</strong> structure role'
    . ' automatically. PDF/UA-1 requires that link annotations have an accessible name,'
    . ' which the library derives from the link text in the structure tree.</p>'
    . '<h2>7 — Rules, Spans and Empty Cells</h2>'
    . '<p>A horizontal rule carries no semantics, so it is emitted as an <strong>Artifact</strong>'
    . ' rather than left as untagged content (PDF/UA-1 7.1):</p>'
    . '<hr>'
    . '<p>Cell <code>colspan</code>/<code>rowspan</code> are recorded on the cell structure'
    . ' element as integer <strong>/ColSpan</strong> and <strong>/RowSpan</strong> attributes,'
    . ' and an empty cell is kept in the tree so the row keeps its full column count (7.2):</p>'
    . '<table border="1" cellspacing="0" cellpadding="3">'
    . '<tr><th>Col A</th><th>Col B</th><th>Col C</th></tr>'
    . '<tr><td colspan="2">Spans columns A and B</td><td>C</td></tr>'
    . '<tr><td rowspan="2">Spans rows</td><td>B2</td><td>C2</td></tr>'
    . '<tr><td>B3</td><td></td></tr>'
    . '</table>';

// A long table that breaks across pages: the repeated header on each continuation
// page is an Artifact, while the single Table structure element keeps all its rows.
$html .=
    '<h2>8 — Page-Spanning Table</h2>'
    . '<table border="1" cellspacing="0" cellpadding="2">'
    . '<thead><tr><th>#</th><th>Description</th></tr></thead>';
for ($row = 1; $row <= 60; ++$row) {
    $html .= '<tr><td>' . $row . '</td><td>Continuation row ' . $row . '</td></tr>';
}

$html .= '</table>';

$html .=
    ''
    . '<h2>9 &ndash; Language Changes (/Lang)</h2>'
    . '<p>The <code>lang</code> attribute sets <strong>/Lang</strong> on the structure element whose'
    . ' language differs from the language in effect. An inline element gets a <strong>Span</strong>,'
    . ' a block without a role of its own a <strong>Div</strong>:</p>'
    . '<p>English text with a Spanish phrase: <span lang="es">Trabajo revisado</span>, then English again.</p>'
    . '<p lang="de">Ein deutscher Absatz: the P element has /Lang (de).</p>'
    . '<div lang="fr"><p>Un paragraphe dans une division fran&ccedil;aise.</p><p>Les deux paragraphes'
    . ' prennent la langue de la Div.</p></div>'
    . '<p>A run in an undetermined language: <span lang="und">xyzzy</span>; a run with an empty'
    . ' attribute, which declares an unknown language and is also written as /Lang (und):'
    . ' <span lang="">plugh</span>.</p>';

// A table row taller than a page continues on the next page: the TD structure element
// holds the content of both pages.
$tallcell = [];
for ($row = 1; $row <= 110; ++$row) {
    $tallcell[] = 'Line ' . $row . ' of a cell taller than a page';
}

$html .=
    '<h2>10 &ndash; Row Taller Than a Page</h2>'
    . '<table border="1" cellspacing="0" cellpadding="2">'
    . '<thead><tr><th>Lines</th></tr></thead>'
    . '<tr><td>'
    . \implode('<br />', $tallcell)
    . '</td></tr></table>';

$pdf->addHTMLCell(html: $html, posx: 15, posy: 20, width: 180);

$rawpdf = $pdf->getOutPDFString();
$pdf->renderPDF(rawpdf: $rawpdf);