Navigation : annotations, liens, signets, actions et pièces jointes

En un coup d’œil

Le module Navigation construit la couche interactive du PDF : annotations, annotations de lien et d’URL, plan du document (signets), table des matières, actions et chaînes de déclencheurs associées, transitions de page, ainsi que pièces jointes de fichiers embarqués avec leurs relations de fichier associé.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

La norme ISO 32000-2 §12 définit les fonctionnalités interactives d’un PDF — annotations, actions, destinations et plan du document. Dans le moteur, ce module encode cette couche. Il s’articule autour de classes gestionnaires qui accumulent l’intention, puis d’objets-valeur qu’elles émettent.

AnnotationManager est la surface d’API la plus étendue. Il ajoute des annotations de texte, de texte libre, de ligne, de carré, de cercle, de polygone, de polyligne, d’encre et de balisage de texte (surlignage, soulignement). Il applique des protections strictes : un sous-type d’annotation inconnu est ramené à une valeur par défaut sûre, un nom d’icône qui n’est pas un jeton de nom PDF valide est remplacé, et les QuadPoints de balisage de texte doivent être fournis sous forme d’un multiple de huit flottants ; sinon, ils sont abandonnés. Ce sont des défenses contre l’injection PDF, pas de simples facilités de validation. LinkManager gère les liens internes, les destinations nommées et les annotations d’URL. Il préalloue les objets d’annotation afin que le Writer puisse les référencer avant leur sérialisation.

BookmarkManager et TocBuilder construisent la hiérarchie de navigation. Le plan du document est l’arbre de signets qu’un lecteur affiche dans sa barre latérale ; TocBuilder rend une table des matières sur la page et peut utiliser FontMetrics pour calculer la mise en page leader/width. OutlineAutoGenerator dérive un plan à partir de la structure du document.

La hiérarchie Action dans NextPDF\Navigation\Action modélise les comportements pilotés par déclencheur : GoTo (distant et embarqué), lancement, action nommée, masquage, reset/submit de formulaire, et définition de l’état du contenu optionnel. L’action de rendition de l’annotation d’écran du §13 est différée : elle relève d’un travail futur et n’est pas encore câblée, donc ne t’appuie pas dessus comme sur une action prise en charge. Action::withNext() construit la chaîne d’actions qu’un seul événement déclencheur exécute. PageTransition modélise une transition de présentation. FileAttachment embarque un fichier depuis un chemin ou une chaîne d’octets et lui associe un AFRelationship (l’énumération de la relation de fichier associé). Il renvoie un FileAttachmentResult et écrit via writeAttachments(). Les gestionnaires du cœur sont @since 1.0.0. La hiérarchie d’actions est @since 2.1.0. Le constructeur de FileAttachment, ainsi que AFRelationship, ont été ajoutés en @since 1.8.0 / @since 1.1.0.

Surface de l’API

Classe	Membres clés	Rôle
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Construction d’annotations avec entrées protégées contre l’injection (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Liens internes, destinations nommées, annotations d’URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Arbre du plan du document (signets) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Table des matières sur la page (@since 1.0.0)
Action (interface)	subtype(), toDictionary(), withNext(), nextChain()	Action déclenchée et chaîne d’actions (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Transition de page en mode présentation (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Pièces jointes de fichiers embarqués (@since 1.0.0)
AFRelationship (énumération)	toPdfName()	Relation de fichier associé (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Jeu de drapeaux d’annotation immuable (@since 1.2.0)

Exécute composer docs:generate-api-php -- --module=Navigation pour obtenir le tableau PHPDoc complet.

Exemple de code — Démarrage rapide

Source : examples/12-bookmarks-and-toc.php construit le plan du document via la façade de haut niveau qui encapsule BookmarkManager. Pour travailler directement avec le gestionnaire :

<?php

declare(strict_types=1);

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

use NextPDF\Navigation\BookmarkManager;

$bookmarks = new BookmarkManager();
$bookmarks->addBookmark(title: 'Chapter 1', level: 0, pageIndex: 0);
$bookmarks->addBookmark(title: '1.1 Overview', level: 1, pageIndex: 0);
$bookmarks->addBookmark(title: 'Chapter 2', level: 0, pageIndex: 4);

if ($bookmarks->hasBookmarks()) {
    // The Writer calls $bookmarks->write(...) during catalog serialization.
}

Exemple de code — Production

Embarque une pièce jointe avec une relation de fichier associé explicite, puis vérifie le résultat avant de finaliser le document.

<?php

declare(strict_types=1);

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

use NextPDF\Navigation\AFRelationship;
use NextPDF\Navigation\FileAttachment;

$attachments = new FileAttachment();

$attachments->embedFile(
    path: '/srv/invoices/INV-2026-0042.xml',
    description: 'Structured invoice source (Factur-X)',
    afRelationship: AFRelationship::Source,
);

if ($attachments->hasAttachments()) {
    // writeAttachments() is invoked by the Writer with a live ObjectRegistry;
    // getCount() lets the application assert the expected attachment count.
    assert($attachments->getCount() === 1);
}

Cas limites & pièges

• AnnotationManager normalise silencieusement les entrées hostiles : un sous-type invalide devient la valeur par défaut, une icône qui n’est pas un nom PDF valide devient l’icône par défaut, et les QuadPoints malformés sont abandonnés. L’annotation est tout de même produite — vérifie tes entrées en amont si tu as besoin qu’elles soient respectées à l’identique.
• LinkManager::preallocateAnnotationObjects() doit être exécuté avant que le Writer ne sérialise les références, sinon les cibles des liens restent sans résolution.
• Action::withNext() renvoie une nouvelle action à laquelle la chaîne est attachée ; l’interface est conçue pour un chaînage immuable, pas pour muter l’instance en place.
• FileAttachment::writeAttachments() requiert un ObjectRegistry actif fourni par le Writer. Appelé isolément, le gestionnaire accumule l’intention mais n’écrit rien tant que le Writer ne le pilote pas.
• AnnotationFlags est un jeu de drapeaux immuable. with()/without() renvoient une nouvelle instance ; l’original est inchangé.

Performance

L’accumulation d’annotations, de liens et de signets est en O(n) sur le nombre d’éléments, sans recomposition. Le coût d’un fichier embarqué en pièce jointe est dominé par le volume d’octets embarqués, pas par le gestionnaire. La charge de travail de référence par défaut respecte le budget de 1500 ms de temps mural / 64 Mo en pic. Le profil de reproductibilité est structural : les numéros d’objet et le /ID du trailer diffèrent d’une exécution à l’autre. Deux documents avec la même intention de navigation sont structurellement égaux, mais pas identiques octet pour octet.

Notes de sécurité

AnnotationManager traite le sous-type d’annotation, l’icône et les QuadPoints comme non fiables : chacun est validé contre une liste d’autorisation ou un motif, et une valeur incorrecte est remplacée plutôt qu’écrite telle quelle. Ce mécanisme ferme un vecteur d’injection de nom PDF. LinkManager::addUrlAnnotation() encode une URL dans une action de lien. L’URL relève du modèle de confiance du consommateur — une URL hostile est une URL valide, donc assainis les destinations avant de les ajouter. FileAttachment embarque des octets arbitraires. Borne la taille embarquée et traite la source de la pièce jointe comme non fiable lorsqu’elle provient d’un utilisateur. Consulte le modèle de menace du moteur dans /modules/core/security/.

Conformité

Les structures que ce module émet suivent ISO 32000-2 §12 — annotations, actions, destinations — et la hiérarchie du plan du document. Les références aux clauses par fonctionnalité (icônes d’annotation §12.5.6.4, QuadPoints de balisage de texte §12.5.6.10, actions §12.6) sont documentées en ligne dans src/Navigation/ et exercées par tests/Unit/Navigation/. Ce sont des faits d’implémentation, pas une déclaration de conformité PDF 2.0 de bout en bout. La conformité du document complet est validée par l’oracle et les suites de référence décrites dans /modules/core/conformance/.

Voir aussi

• Module Document
• Module Multimédia — les objets de rendition que lance une action de rendition.
• Module Writer — sérialise les structures de navigation.
• Vue d’ensemble de la conformité
• Modèle de sécurité du moteur