Lesezeichen und Inhaltsverzeichnis hinzufügen

Auf einen Blick

Dieses Recipe fügt eine hierarchische Dokumentstruktur aus Lesezeichen hinzu. Die Reader-Anwendung führt diese Einträge in ihrer Navigationsleiste auf; dort dienen sie zugleich als anklickbares Inhaltsverzeichnis. Ein ganzzahliges Level steuert die Verschachtelung. Das Recipe orientiert sich an examples/12-bookmarks-and-toc.php.

ISO 32000-2 nennt dies die Dokumentstruktur (document outline): eine baumförmig strukturierte Hierarchie aus Outline-Einträgen, die als visuelles Inhaltsverzeichnis dient.

Installation

composer require nextpdf/core:^3

Es ist keine optionale Extension erforderlich. Die Lesezeichen-API ist seit 1.0.0 stabil und läuft auf der Backport-Matrix 8.1–8.4.

Konzeptioneller Überblick

bookmark($title, $level, $y) fügt einen Outline-Eintrag hinzu, der an die aktuelle Seite gebunden ist. Die Bindung verwendet das aktuelle Y oder ein explizites Y. $level legt die Verschachtelungstiefe fest: Level 0 ist ein Kapitel auf oberster Ebene, Level 1 ein Abschnitt unter dem jüngsten Eintrag der Ebene 0 und so weiter. Die Engine baut den Outline-Baum für Sie auf. ISO 32000-2 verkettet die Einträge auf jeder Ebene über Prev/Next und verschachtelt sie über First/Last, wobei der Outlines-Eintrag des Katalogs die Wurzel bildet.

Jeder Eintrag enthält ein Ziel, sodass der Reader zur richtigen Seite springt, wenn Sie das Lesezeichen anklicken. ISO 32000-2 §12.3.2 legt fest, dass Ziele mit Outline-Einträgen verknüpft werden dürfen. Derselbe Aufruf speist auch den Inhaltsverzeichnis-Builder von NextPDF, sodass die Outline und ein gerendertes Inhaltsverzeichnis synchron bleiben.

API-Oberfläche

Die API-Oberfläche wird automatisch aus PHPDoc generiert. Dieses Recipe stützt sich auf eine Methode:

bookmark(string $title, int $level = 0, float $y = -1): static — fügt bei $level einen Outline-Eintrag hinzu, der an die aktuelle Seite gebunden ist. $y = -1 nutzt das aktuelle Cursor-Y. Übergeben Sie ein nicht-negatives Y, um ein präzises Ziel festzulegen.

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();

$doc->addPage();
$doc->bookmark('Chapter 1', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 1', newLine: true);

$doc->bookmark('Section 1.1', level: 1); // nested under Chapter 1
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Section body.');

$doc->addPage();
$doc->bookmark('Chapter 2', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 2', newLine: true);

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/bookmarks.pdf');

Codebeispiel — Produktion

Dies ist das vollständige, harness-fertige Beispiel. Es berücksichtigt NEXTPDF_COOKBOOK_OUTPUT und führt keine eigene Entropie ein.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Bookmarks and Navigation');
$doc->setPrintHeader(false);
$doc->setPrintFooter(false);
$doc->setAutoPageBreak(true, margin: 25);

// Chapter 1
$doc->addPage();
$doc->bookmark('Chapter 1: Introduction', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 1: Introduction', newLine: true);
$doc->ln(3);

$doc->bookmark('What is NextPDF?', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'What is NextPDF?', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'NextPDF is a modern PDF 2.0 library for PHP 8.4+. '
    . 'It generates standards-targeting documents with typography, '
    . 'graphics, and signatures.');
$doc->ln(5);

$doc->bookmark('Key Features', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Key Features', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'HTML rendering, barcodes, PAdES signatures, '
    . 'and a worker-safe architecture.');

// Chapter 2
$doc->addPage();
$doc->bookmark('Chapter 2: Getting Started', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 2: Getting Started', newLine: true);
$doc->ln(3);

$doc->bookmark('Installation', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Installation', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Install via Composer: composer require nextpdf/core');

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/bookmarks.pdf';
$doc->save($out);

echo "Created bookmarks.pdf with a 2-level outline\n";

Randfälle & Stolperfallen

Level-Sprünge. Ein Sprung von Level 0 auf Level 2 ohne dazwischenliegendes Level 1 erzeugt in manchen Readern eine fehlerhaft wirkende Hierarchie. Erhöhen Sie das Level jeweils um höchstens eins.
Lesezeichen vor dem Inhalt. Rufen Sie bookmark() an der Stelle auf, an der das Ziel liegen soll. Platzieren Sie den Aufruf in den meisten Fällen unmittelbar vor der Überschrift. Ein Aufruf nach der Überschrift setzt das Ziel etwas darunter.
Explizites Y für präzise Ziele. Mit $y = -1 ist das Ziel das aktuelle Cursor-Y. Übergeben Sie ein explizites Y für ein stabiles Ziel. Ein explizites Y legt zum Beispiel den Anfang eines Abschnitts fest, unabhängig davon, wie viel Inhalt davor steht.
Outline-Unterstützung ist universell, aber die Darstellung variiert. Reader können die Outline ein- oder ausgeklappt darstellen. Diese API kann pro Eintrag keinen offenen oder geschlossenen Zustand erzwingen.

Performance

Jeder bookmark()-Aufruf hängt einen Outline-Eintrag und einen Inhaltsverzeichnis-Eintrag an; das ist O(1)-Arbeit. Der Outline-Baum wird einmalig bei save() fertiggestellt. Hunderte Lesezeichen bleiben deutlich innerhalb des Budgets von 2000 ms / 64 MB.

Sicherheitshinweise

Lesezeichen-Titel werden in der Navigationsoberfläche des Readers dargestellt. Wenn ein Titel benutzergesteuerte Daten enthält, begrenzen Sie seine Länge und bereinigen Sie ihn so, wie Sie es bei jeder angezeigten Zeichenkette tun würden. Dieses Recipe führt kein Parsen von Eingaben und keinen Netzwerkzugriff aus.

Konformität

Aussage	Spezifikation	Abschnitt
Die Dokumentstruktur ist ein Baum aus Outline-Einträgen, der als visuelles Inhaltsverzeichnis fungiert.	ISO 32000-2	§12.3.3
Outline-Einträge sind über `Prev`/`Next` verkettet und über `First`/`Last` verschachtelt.	ISO 32000-2	§12.3.3
Das Outline-Dictionary ist der `Outlines`-Eintrag des Katalogs.	ISO 32000-2	§7.7.2
Ziele dürfen mit Outline-Einträgen verknüpft werden.	ISO 32000-2	§12.3.2

Reproduzierbarkeitsprofil — strukturell. Das Trailer-/ID und die Datums-Atome variieren bei jedem Speichern. Daher entfernt das Harness diese Atome und vergleicht die qpdf-normalisierte Struktur. Dieses Recipe beschreibt, wie NextPDF diese Struktur erzeugt. Es sichert keine pauschale ISO 32000-2-Konformität zu.

Kommerzieller Kontext

Nicht zutreffend. Die Dokumentstruktur und das Inhaltsverzeichnis sind Core-Funktionen ohne Premium-Gate.