Настройка метаданных документа (заголовок, автор, язык)

Кратко

Задайте поля метаданных Portable Document Format (PDF): заголовок, автора, тему, ключевые слова и создателя. Также задайте язык документа. Эти поля записываются в сведения о документе и метаданные уровня документа. Средства просмотра PDF показывают эти данные на панели “Свойства”, а средства поиска и каталогизации могут их индексировать. Этот рецепт основан на examples/16-metadata.php.

Установка

composer require nextpdf/core:^3

Концептуальный обзор

Метаданные — это общие сведения о документе (ISO 32000-2 §14.3). В PDF 2.0 они хранятся в двух местах: в устаревшем словаре сведений о документе и в потоке метаданных Extensible Metadata Platform (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 — тег Best Current Practice (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. Недопустимый тег сохраняется без изменений, и вспомогательные технологии могут его игнорировать. Движок проверяет тег в режиме fail-fast только при включённом строгом режиме тегированного PDF.
setKeywords() принимает одну строку. Передавайте термины через запятую. Движок не разбирает массив PHP за вас.
Взаимодействие с тегированным PDF. Если тегированный PDF будет включён позже, предыдущий явный вызов setLanguage() сохранится. Структурный язык служит только запасным вариантом, когда язык не задан.
Датами управляет движок. Временные метки создания и изменения берутся из часов движка, а стенд воспроизводимости фиксирует эти значения. Именно поэтому профиль — structural, а не bitwise.

Производительность

Настройка метаданных сводится к присваиванию полей за постоянное время и не требует затрат на отрисовку. Эта операция с большим запасом укладывается в бюджет 1000 ms / 64 MB.

Замечания по безопасности

Метаданные хранятся в открытом виде, и их легко извлечь. Не размещайте в полях заголовка, автора, темы, ключевых слов или создателя секреты, внутренние идентификаторы или персональные данные, которые вы не готовы публиковать. Эти поля передаются вместе с файлом и индексируются поисковыми средствами. Очистите метаданные, прежде чем распространять документ, созданный на основе внутреннего шаблона.

Соответствие

Утверждение	Спецификация	Раздел
Метаданные — это общие сведения о документе.	ISO 32000-2	§14.3
Запись `Author` в словаре Info является необязательной и устаревшей в PDF 2.0.	ISO 32000-2	§14.3
К документу может быть прикреплён поток метаданных XMP уровня документа.	ISO 32000-2	§14.3

NextPDF формирует структуры метаданных, описанные в приведённых разделах. Это не является заявлением о полном соответствии ISO 32000-2.