设置文档元数据（标题、作者、语言）

概览

设置文档的元数据字段（标题、作者、主题、关键字、创建者）以及文档语言。这些字段会写入文档信息和文档级元数据。PDF 阅读器会在“Properties”面板中显示这些数据，搜索和编目工具也会为其建立索引。本示例遵循 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。