내비게이션: 주석, 링크, 개요, 액션, 첨부 파일
한눈에 보기
섹션 제목: “한눈에 보기”Navigation 모듈은 PDF의 대화형 내비게이션 계층을 구성합니다. 이 계층에는 주석, 링크 및 URL 주석, 문서 개요(북마크)와 목차, 액션 및 트리거 체인, 페이지 전환, 연관 파일 관계가 지정된 임베디드 파일 첨부가 포함됩니다.
composer require nextpdf/core:^3개념 개요
섹션 제목: “개념 개요”ISO 32000-2 §12는 PDF의 대화형 기능인 주석, 액션, 대상, 문서 개요를 정의합니다. 이 모듈은 엔진에서 해당 계층을 인코딩하는 구성 요소입니다. 의도를 누적하는 매니저 클래스 집합과 매니저가 생성하는 값 객체 집합으로 구성됩니다.
AnnotationManager가 가장 넓은 API 표면을 제공합니다. 텍스트, 자유 텍스트, 선, 사각형, 원, 다각형, 폴리라인, 잉크, 그리고 텍스트 마크업 주석(하이라이트, 밑줄)을 추가합니다. 이 클래스는 견고하게 동작합니다. 알 수 없는 주석 하위 유형은 안전한 기본값으로 폴백되고, 유효한 PDF 이름 토큰이 아닌 아이콘 이름은 대체되며, 텍스트 마크업 QuadPoints는 부동소수점 값의 개수가 8의 배수로 전달되어야 하고 그렇지 않으면 폐기됩니다. 이는 검증 편의 기능이 아니라 PDF 인젝션 방어입니다. LinkManager는 내부 링크, 명명된 대상, URL 주석을 처리합니다. Writer가 직렬화되기 전에 주석 객체를 참조할 수 있도록 미리 할당합니다.
BookmarkManager와 TocBuilder는 내비게이션 계층 구조를 구성합니다. 문서 개요는 뷰어가 사이드바에 표시하는 북마크 트리입니다. TocBuilder는 페이지 내 목차를 렌더링하며 leader/width 레이아웃을 위해 FontMetrics를 사용할 수 있습니다. OutlineAutoGenerator는 문서 구조에서 개요를 도출합니다.
NextPDF\Navigation\Action 아래의 Action 계층 구조는 트리거 기반 동작을 모델링합니다. 여기에는 GoTo(원격 및 임베디드), 실행, 명명, 숨기기, reset/submit 폼, 선택적 콘텐츠 상태 설정이 포함됩니다. §13 화면 주석 렌디션 액션은 지원이 연기되었습니다. 향후 작업 항목이며 아직 연결되어 있지 않으므로 지원되는 액션으로 의존하지 마십시오. Action::withNext()는 단일 트리거 이벤트가 실행하는 액션 체인을 구성합니다. PageTransition은 프레젠테이션 전환을 모델링합니다. FileAttachment는 경로나 바이트 문자열에서 파일을 임베드하고 AFRelationship(연관 파일 관계 열거형)으로 태그를 지정합니다. 이 작업은 FileAttachmentResult를 반환하며, 기록은 writeAttachments()를 통해 수행됩니다. 코어 매니저는 @since 1.0.0입니다. 액션 계층 구조는 @since 2.1.0입니다. FileAttachment 생성자와 AFRelationship은 각각 @since 1.8.0 / @since 1.1.0에 도입되었습니다.
API 표면
섹션 제목: “API 표면”| 클래스 | 주요 멤버 | 역할 |
|---|---|---|
AnnotationManager | addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline() | 인젝션에 안전한 입력 처리를 갖춘 주석 빌더 (@since 1.0.0) |
LinkManager | addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects() | 내부 링크, 명명된 대상, URL 주석 (@since 1.0.0) |
BookmarkManager | addBookmark(), hasBookmarks(), write() | 문서 개요(북마크) 트리 (@since 1.0.0) |
TocBuilder | addEntry(), hasEntries(), render(), getEntries() | 페이지 내 목차 (@since 1.0.0) |
Action (인터페이스) | subtype(), toDictionary(), withNext(), nextChain() | 트리거 액션 + 액션 체인 (@since 2.1.0) |
PageTransition | toDict(), toInlineDict() | 프레젠테이션 페이지 전환 (@since 1.2.0) |
FileAttachment | embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments() | 임베디드 파일 첨부 (@since 1.0.0) |
AFRelationship (열거형) | toPdfName() | 연관 파일 관계 (@since 1.1.0) |
AnnotationFlags | with(), without(), has(), toInt() | 불변 주석 플래그 집합 (@since 1.2.0) |
전체 PHPDoc 표를 보려면 composer docs:generate-api-php -- --module=Navigation를 실행하십시오.
코드 샘플 — 빠른 시작
섹션 제목: “코드 샘플 — 빠른 시작”소스인 examples/12-bookmarks-and-toc.php는 BookmarkManager를 래핑하는 고수준 파사드를 통해 문서 개요를 구성합니다. 매니저를 직접 사용할 때는 다음과 같습니다:
<?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.}코드 샘플 — 프로덕션
섹션 제목: “코드 샘플 — 프로덕션”명시적인 연관 파일 관계를 지정해 첨부를 임베드하고 문서가 최종화되기 전에 결과를 확인하십시오.
<?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);}엣지 케이스 및 주의 사항
섹션 제목: “엣지 케이스 및 주의 사항”AnnotationManager는 적대적인 입력을 자동으로 정규화합니다. 유효하지 않은 하위 유형은 기본값으로 대체되고, 이름 형식이 아닌 아이콘은 기본 아이콘으로 대체되며, 잘못된 형식의QuadPoints는 폐기됩니다. 주석 자체는 여전히 생성됩니다. 입력을 그대로 정확히 반영해야 한다면 상위 단계에서 입력을 검증하십시오.LinkManager::preallocateAnnotationObjects()는 Writer가 참조를 직렬화하기 전에 실행되어야 하며, 그렇지 않으면 링크 대상이 아무것도 가리키지 않게 됩니다.Action::withNext()는 체인이 연결된 새로운 액션을 반환합니다. 이 인터페이스는 제자리 변경이 아닌 불변 체이닝을 위해 설계되었습니다.FileAttachment::writeAttachments()는 Writer로부터 활성ObjectRegistry를 필요로 합니다. 매니저를 단독으로 호출하면 의도는 누적되지만 Writer가 구동하기 전까지는 아무것도 기록되지 않습니다.AnnotationFlags는 불변 플래그 집합입니다.with()/without()은 새 인스턴스를 반환하며 원본은 변경되지 않습니다.
주석, 링크, 북마크 누적은 항목 개수에 대해 O(n)이며 리플로우가 없습니다. 임베디드 파일 첨부 비용은 매니저 자체가 아니라 임베드된 바이트 크기에 좌우됩니다. 기본 레퍼런스 워크로드는 1500 ms 벽시계 / 64 MB 피크 예산 이내에 들어갑니다. 재현성 프로필은 structural입니다. 객체 번호와 트레일러 /ID는 실행마다 달라집니다. 동일한 내비게이션 의도를 가진 두 문서는 구조적으로는 동등하지만 바이트 단위로 동일하지는 않습니다.
보안 참고 사항
섹션 제목: “보안 참고 사항”AnnotationManager는 주석 하위 유형, 아이콘, QuadPoints를 신뢰할 수 없는 것으로 취급합니다. 각 값은 허용 목록이나 패턴으로 검증되며, 잘못된 값은 그대로 기록하지 않고 대체됩니다. 이는 PDF 이름 인젝션 벡터를 차단합니다. LinkManager::addUrlAnnotation()는 URL을 링크 액션으로 인코딩합니다. URL의 신뢰 여부는 소비자가 책임져야 합니다. 적대적인 URL도 유효한 URL이므로 대상을 추가하기 전에 정제하십시오. FileAttachment는 임의의 바이트를 임베드합니다. 임베드 크기를 제한하고 사용자가 제공한 첨부 소스는 신뢰할 수 없는 것으로 취급하십시오. /modules/core/security/의 엔진 위협 모델을 참조하십시오.
준수성
섹션 제목: “준수성”이 모듈이 생성하는 구조는 ISO 32000-2 §12 — 주석, 액션, 대상 — 및 문서 개요 계층 구조를 따릅니다. 기능별 조항 참조(주석 아이콘 §12.5.6.4, 텍스트 마크업 QuadPoints §12.5.6.10, 액션 §12.6)는 src/Navigation/에 인라인으로 문서화되어 있으며 tests/Unit/Navigation/에서 검증됩니다. 이는 구현 사실을 설명하는 것이며 전체 PDF 2.0 준수성에 대한 진술이 아닙니다. 전체 문서 준수성은 /modules/core/conformance/에 설명된 오라클 및 골든 스위트로 검증됩니다.
참고 항목
섹션 제목: “참고 항목”- Document 모듈
- Multimedia 모듈 — 렌디션 액션이 재생하는 렌디션 객체를 다룹니다.
- Writer 모듈 — 내비게이션 구조를 직렬화합니다.
- 준수성 개요
- 엔진 보안 모델