Navigation (HasNavigation)

The HasNavigation trait and its underlying modules (BookmarkManager, TocManager, AnnotationManager, FileAttachment) provide PDF navigation features: hierarchical bookmarks, auto-generated table of contents, internal and external links, named destinations, annotations, and embedded file attachments. All methods return static, so every call can be chained.

Quick Reference

Method	Feature
bookmark()	Add a hierarchical bookmark / outline entry
addTOC()	Auto-generate a table of contents with dot leaders
addHTMLTOC()	HTML-styled table of contents
addLink()	Create an internal link destination (returns link ID)
setLink()	Set an internal link target position
setDestination()	Create a named destination anchor
annotation()	Add a text annotation
addFileAttachment()	Embed a file attachment in the PDF

Basic Example

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)

    // Bookmarks
    ->bookmark('Chapter 1', 0)
    ->cell(0, 10, 'Chapter 1: Introduction', newLine: true)
    ->bookmark('Section 1.1', 1)
    ->cell(0, 10, '1.1 Getting Started', newLine: true)

    // Internal link
    ->addPage()
    ->bookmark('Chapter 2', 0)
    ->cell(0, 10, 'Chapter 2: Advanced Topics', newLine: true)

    // File attachment
    ->addFileAttachment('/path/to/data.xlsx', 'data.xlsx', 'Supporting data')

    // Auto-generate TOC at the end (inserts at page 1)
    ->addTOC(1, ' . ', 'Table of Contents');

Bookmarks / Outlines

$pdf->bookmark(string $txt, int $level = 0, float $y = -1, int $page = -1, string $style = '', array $color = []);

Bookmarks appear in the PDF reader's outline panel. Nest them by incrementing $level.

Table of Contents

$pdf->addTOC(int $page, string $numberSuffix = '', string $bookmarkText = '');

Call addTOC() after all bookmarks have been added. The TOC is built from the bookmark tree and inserted at the specified page position. Use addHTMLTOC() for full control over entry styling via HTML and CSS.

Internal Links

Create clickable cross-references between pages:

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12);

$linkId = $pdf->addLink();

$pdf->write(10, 'Jump to Chapter 2', link: $linkId)
    ->addPage()
    ->setLink($linkId, y: 0)
    ->cell(0, 10, 'Chapter 2 starts here', newLine: true);

External Links

Pass a URL string as the $link parameter on cell(), write(), or image():

$pdf->cell(0, 10, 'Visit our website', link: 'https://example.com', newLine: true)
    ->write(10, 'Click here', link: 'https://docs.example.com');

Named Destinations

$pdf->setDestination(string $name, float $y = -1, int $page = -1);

Named destinations allow external documents or URLs to link to a specific location via the #name fragment.

Annotations

$pdf->annotation(float $x, float $y, float $w, float $h, string $text, array $opt = []);

Annotations appear as sticky-note icons in the PDF viewer.

$pdf->annotation(50, 80, 10, 10, 'Review this section before release.', [
    'subtype' => 'Text',
    'icon'    => 'Comment',
    'color'   => [255, 255, 0],
]);

File Attachments

$pdf->addFileAttachment(string $file, string $name, string $desc);

Embedded files appear in the PDF reader's attachment panel.

$pdf->addFileAttachment('/reports/q4-data.xlsx', 'q4-data.xlsx', 'Q4 financial data')
    ->addFileAttachment('/reports/methodology.pdf', 'methodology.pdf', 'Research methodology');