Bookmarks and Hyperlinks

Bookmarks and Hyperlinks

A document can declare a sidebar table of contents (the bookmarks panel) and place clickable areas anywhere on its pages. Both features are built around the same Destination value object, which points to a page and an optional position or zoom.

Basic example

use DragonOfMercy\PhpPdf\Document;
use DragonOfMercy\PhpPdf\Unit;
use DragonOfMercy\PhpPdf\Outline\Destination;
use DragonOfMercy\PhpPdf\Outline\Link;

$pdf = new Document(Unit::PT);
$page1 = $pdf->addPage();
$page1->text(50, 60, 'Chapter 1');
$page2 = $pdf->addPage();
$page2->text(50, 60, 'Chapter 2');

// Sidebar table of contents (shown in the Bookmarks panel).
$root = $pdf->outline();
$chap1 = $root->add('Chapter 1', Destination::page(0));
$chap1->add('Section 1.1', Destination::page(0));
$root->add('Chapter 2', Destination::page(1));

// Clickable areas on the page.
$page1->link(50, 100, 200, 14, Link::url('https://example.com'));
$page1->link(50, 120, 200, 14, Link::destination(Destination::page(1)));

$pdf->save('document.pdf');

Bookmarks ($pdf->outline())

$pdf->outline() returns the root OutlineNode. The root carries no title; all visible entries are added as children via add().

OutlineNode::add(string $title, Destination $destination): OutlineNode

add() returns the new child node, so you can either descend into it to add sub-items or capture the parent and add siblings from there.

$root = $pdf->outline();
$chap = $root->add('Chapter 1', Destination::page(0)); // top-level entry
$chap->add('Section 1.1', Destination::page(0));       // child of Chapter 1
$chap->add('Section 1.2', Destination::page(1));
$root->add('Chapter 2', Destination::page(2));         // sibling of Chapter 1

To show the bookmarks panel automatically when the document opens, set PageMode::USE_OUTLINES (see Viewer Preferences).

Destination

Pages are 0-indexed throughout Destination (page 0 is the first page). Coordinates use the document unit and the top-down Y axis, consistent with Page::text() and Page::cell().

Named constructor	Description
Destination::page(int $pageIndex)	Jump to the top-left of $pageIndex at the viewer's current zoom. Safe default.
Destination::xyz(int $pageIndex, ?float $left, ?float $top, ?float $zoom = null)	Arbitrary top-left position and zoom. null for any argument keeps the viewer's current value (PDF spec section 12.3.2.2).
Destination::fit(int $pageIndex)	Fit the entire page in the viewport.
Destination::fitWidth(int $pageIndex, ?float $top = null)	Fit page width; scroll so $top (document unit, top-down) appears at the viewport top. null keeps the current scroll.

Out-of-range page indices throw PdfException at output() / save() time.

Hyperlinks ($page->link())

Place a clickable rectangle on a page.

Page::link(float $x, float $y, float $width, float $height, Link $link): self

• $x, $y - top-left corner of the clickable area, in the document unit with a top-down Y axis.
• $width, $height - dimensions of the clickable area.
• $link - the action to perform (see below).

Link named constructors

Constructor	Description
Link::url(string $href)	External URI action (web URL, mailto, etc.). An empty $href throws PdfException.
Link::destination(Destination $dest)	Internal GoTo action - jumps to a position inside the same document.

See also

• Viewer Preferences