設定文件中繼資料（標題、作者、語言）

概覽

設定文件的中繼資料欄位（標題、作者、主旨、關鍵字、建立者）與文件語言。這些欄位會寫入文件資訊與文件層級的中繼資料。PDF 閱讀器會在「Properties」面板顯示這些資料，搜尋與編目工具也會替它們建立 Index（索引）。本範例依循 examples/16-metadata.php。

安裝

composer require nextpdf/core:^3

概念說明

中繼資料是描述文件的一般資訊（ISO 32000-2 §14.3）。PDF 2.0 會將其放在兩個位置：舊有的文件資訊字典，以及文件層級的 XMP 中繼資料串流。在 PDF 2.0 中，多數資訊字典欄位（包含 Author）都明確標示為 選用且已棄用，改以 XMP 為主。

其中 HasMetadata 的 setter 會填入引擎的中繼資料模型，writer 則寫出對應項目。setLanguage() 會設定目錄中的 /Lang，供輔助科技使用。這個設定檔之所以標示為 structural，是因為文件帶有 trailer 的 /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 — 唯讀存取子，用於讀取目前的 tagged 模式

程式碼範例 — 快速上手

<?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。無效的標籤會原樣儲存，也可能被輔助科技忽略。引擎只有在啟用 tagged-PDF 嚴格模式時，才會對標籤做快速失敗驗證。
setKeywords() 接受單一字串。 請傳入以逗號分隔的詞彙。引擎不會為你拆分 PHP 陣列。
與 tagged-PDF 的互動。 之後啟用 tagged 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。