ドキュメントのメタデータ（タイトル、作成者、言語）を設定する

概要

ドキュメントのメタデータフィールド（タイトル、作成者、サブジェクト、キーワード、作成ツール）と、ドキュメントの言語を設定します。これらのフィールドは、ドキュメント情報とドキュメントレベルのメタデータに反映されます。PDF リーダーはこのデータを「プロパティ」パネルに表示し、検索ツールやカタログ作成ツールはこのデータをインデックス化します。このレシピは examples/16-metadata.php に基づいています。

インストール

composer require nextpdf/core:^3

概念の概要

メタデータとは、ドキュメントに関する一般的な情報です（ISO 32000-2 §14.3）。PDF 2.0 は、この情報を 2 か所に保持します。つまり、従来のドキュメント情報ディクショナリと、ドキュメントレベルの XMP メタデータストリームです。PDF 2.0 では、Author を含むほとんどの情報ディクショナリフィールドは、XMP が優先されるため明示的に オプションかつ非推奨 とされています。

トレイト HasMetadata のセッターは、エンジンのメタデータモデルに値を設定し、ライターは対応するエントリを出力します。setLanguage() は、支援技術が使用するカタログの /Lang を設定します。プロファイルが structural であるのは、ドキュメントがトレーラーの /ID とメタデータの日付を保持しており、ポストパス処理が 2 回の実行を比較する前にその両方を正規化するためです。

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
PDF 2.0 でオプションかつ非推奨の Info ディクショナリ `Author` エントリ	ISO 32000-2	§14.3
ドキュメントに添付可能なドキュメントレベルの XMP メタデータストリーム	ISO 32000-2	§14.3

NextPDF は、引用された箇条で説明されているメタデータ構造を出力します。ただし、ISO 32000-2 への全面的な準拠を主張するものではありません。