문서 메타데이터 설정(제목, 작성자, 언어)

한눈에 보기

문서 메타데이터 필드(제목, 작성자, 주제, 키워드, 작성 도구)와 문서 언어를 설정합니다. 이 필드는 문서 정보와 문서 수준 메타데이터를 채웁니다. PDF 리더는 이 데이터를 “속성” 패널에 표시하고, 검색 및 카탈로그 작성 도구는 이를 색인합니다. 이 레시피는 examples/16-metadata.php를 따릅니다.

설치

composer require nextpdf/core:^3

개념 개요

메타데이터는 문서에 대한 일반 정보입니다(ISO 32000-2 §14.3). PDF 2.0은 이를 레거시 문서 정보 딕셔너리와 문서 수준 XMP 메타데이터 스트림, 두 곳에 담습니다. PDF 2.0에서는 Author를 비롯한 대부분의 정보 딕셔너리 필드가 XMP를 우선하는 방향으로 명시적으로 선택 사항이며 사용 중단됨으로 지정되어 있습니다.

이 HasMetadata 세터는 엔진의 메타데이터 모델을 채우고, 작성기는 해당 항목을 출력합니다. setLanguage()는 보조 기술이 사용하는 카탈로그 /Lang를 설정합니다. 프로필이 structural인 이유는 문서가 트레일러 /ID와 메타데이터 날짜를 담고 있기 때문입니다. 사후 처리 과정은 두 실행을 비교하기 전에 두 값을 모두 정규화합니다.

API 표면

NextPDF\Core\Concerns\HasMetadata(Document에 믹스인됨):

setTitle(string $title): static
setAuthor(string $author): static
setSubject(string $subject): static
setKeywords(string $keywords): static
setCreator(string $creator): static
setLanguage(string $lang): static — BCP-47 태그(en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — 활성 태그 모드를 확인하는 읽기 전용 접근자

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();

$doc->setTitle('Quarterly Report Q1 2026');
$doc->setAuthor('Reporting Team');
$doc->setSubject('Financial summary');
$doc->setKeywords('finance, quarterly, report');
$doc->setCreator('NextPDF Core');
$doc->setLanguage('en');

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'See File > Properties for the metadata.', newLine: true);

$doc->save(__DIR__ . '/with-metadata.pdf');
echo "Wrote with-metadata.pdf\n";

코드 샘플 — 프로덕션

아래의 전체 예제는 examples/16-metadata.php를 그대로 반영합니다. 이 예제는 하니스에서 사용할 수 있도록 NEXTPDF_COOKBOOK_OUTPUT에 기록합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$metadata = [
    'Title'    => 'NextPDF Metadata Example',
    'Author'   => 'NextPDF Documentation Team',
    'Subject'  => 'Demonstrating PDF 2.0 document metadata fields',
    'Keywords' => 'nextpdf, pdf, metadata, document-properties, php',
    'Creator'  => 'NextPDF Core v3.0',
    'Language' => 'en',
];

$doc = Document::createStandalone();
$doc->setTitle($metadata['Title']);
$doc->setAuthor($metadata['Author']);
$doc->setSubject($metadata['Subject']);
$doc->setKeywords($metadata['Keywords']);
$doc->setCreator($metadata['Creator']);
$doc->setLanguage($metadata['Language']);

$doc->addPage();
$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Document Metadata', newLine: true);
$doc->ln(4);

$doc->setFont('helvetica', '', 11);
$doc->cell(0, 8, 'The following fields are embedded in this PDF.', newLine: true);
$doc->cell(0, 8, 'Open File > Properties in your reader to verify.', newLine: true);
$doc->ln(6);

$doc->setFont('helvetica', 'B', 11);
$doc->cell(40, 9, 'Field', border: true);
$doc->cell(0, 9, 'Value', border: true, newLine: true);
foreach ($metadata as $field => $value) {
    $doc->setFont('helvetica', 'B', 10);
    $doc->cell(40, 9, $field, border: true);
    $doc->setFont('helvetica', '', 10);
    $doc->cell(0, 9, $value, border: true, newLine: true);
}

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

echo "Wrote document with metadata\n";

예상 출력:

Wrote document with metadata

엣지 케이스 및 주의 사항

PDF 2.0은 Info 딕셔너리 필드를 사용 중단합니다. Author 및 기타 정보 딕셔너리 항목은 PDF 2.0에서 선택 사항이며 사용 중단되었습니다. PDF 2.0 소비자에게는 XMP 스트림이 기준이 되는 메타데이터입니다. NextPDF는 호환성을 위해 두 가지를 모두 출력하므로, 엄격한 PDF 2.0 리더가 Info 필드를 표시할 것이라고 가정하지 마십시오.
언어는 BCP-47입니다. zh-Hant-TW를 사용하고, zh_TW나 Chinese는 사용하지 마십시오. 잘못된 태그는 그대로 저장되며 보조 기술에서 무시될 수 있습니다. 엔진은 태그된 PDF 엄격 모드가 활성화된 경우에만 태그를 즉시 실패 방식으로 검증합니다.
setKeywords()는 단일 문자열을 받습니다. 쉼표로 구분된 용어를 전달하십시오. 엔진은 PHP 배열을 자동으로 분리해 주지 않습니다.
태그된 PDF와의 상호 작용. 나중에 태그된 PDF가 활성화되더라도 먼저 명시적으로 호출한 setLanguage() 호출은 유지됩니다. 구조적 언어는 아무것도 설정되지 않은 경우에만 사용되는 폴백입니다.
날짜는 엔진이 관리합니다. 생성 및 수정 타임스탬프는 엔진의 클록에서 가져오며, 재현성 하니스가 이를 고정합니다. 그렇기 때문에 프로필은 structural이며 bitwise가 아닙니다.

성능

메타데이터 설정은 렌더링 비용 없이 상수 시간에 수행되는 필드 할당입니다. 따라서 1000 ms / 64 MB 예산 안에 충분히 들어옵니다.

보안 참고 사항

메타데이터는 평문으로 저장되며 쉽게 추출할 수 있습니다. 공개해서는 안 되는 비밀, 내부 식별자 또는 개인 데이터를 제목, 작성자, 주제, 키워드 또는 작성 도구 필드에 넣지 마십시오. 이러한 필드는 파일과 함께 전달되고 검색 도구에 의해 색인됩니다. 내부 템플릿에서 파생된 문서를 배포하기 전에 메타데이터를 제거하십시오.

적합성

설명	사양	조항
메타데이터는 문서에 대한 일반 정보입니다.	ISO 32000-2	§14.3
Info 딕셔너리 `Author` 항목은 PDF 2.0에서 선택 사항이며 사용 중단되었습니다.	ISO 32000-2	§14.3
문서 수준 XMP 메타데이터 스트림을 문서에 첨부할 수 있습니다.	ISO 32000-2	§14.3

NextPDF는 인용된 조항에 설명된 메타데이터 구조를 출력합니다. 완전한 ISO 32000-2 적합성을 주장하지는 않습니다.