Dokumentmetadaten setzen (Titel, Autor, Sprache)

Auf einen Blick

Setzen Sie die Metadatenfelder des Dokuments (Titel, Autor, Betreff, Schlüsselwörter, Ersteller) und die Dokumentsprache. Diese Felder befüllen die Dokumentinformationen und die Metadaten auf Dokumentebene. PDF-Reader zeigen diese Daten im Bereich „Eigenschaften“ an; Such- und Katalogisierungswerkzeuge indexieren sie. Dieses Recipe folgt examples/16-metadata.php.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Metadaten sind allgemeine Informationen über ein Dokument (ISO 32000-2 §14.3). PDF 2.0 sieht sie an zwei Stellen vor: im veralteten Dokumentinformations-Dictionary und in einem XMP-Metadaten-Stream auf Dokumentebene. In PDF 2.0 sind die meisten Felder des Informations-Dictionary, darunter Author, zugunsten von XMP ausdrücklich optional und veraltet.

Die Setter von HasMetadata befüllen das Metadatenmodell der Engine; der Writer gibt die entsprechenden Einträge aus. setLanguage() setzt den /Lang-Eintrag im Catalog, den assistive Technologien nutzen. Das Profil ist structural, weil das Dokument ein /ID im Trailer und ein Metadatendatum trägt; der Post-Pass normalisiert beides, bevor er zwei Durchläufe vergleicht.

API-Oberfläche

NextPDF\Core\Concerns\HasMetadata (eingemischt in 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-Tag (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — schreibgeschützter Accessor für den aktiven Tagged-Modus

Codebeispiel — Schnellstart

<?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";

Codebeispiel — Produktion

Das vollständige Beispiel unten entspricht examples/16-metadata.php. Für den Harness schreibt es nach 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";

Erwartete Ausgabe:

Wrote document with metadata

Sonderfälle & Fallstricke

PDF 2.0 erklärt die Felder des Info-Dictionary für veraltet. Author und die übrigen Einträge des Informations-Dictionary sind in PDF 2.0 optional und veraltet. Für einen PDF 2.0-Consumer ist der XMP-Stream die maßgebliche Metadatenquelle. NextPDF gibt aus Kompatibilitätsgründen beide aus; gehen Sie daher nicht davon aus, dass ein strikter PDF 2.0-Reader die Info-Felder anzeigt.
Die Sprache ist BCP-47. Verwenden Sie zh-Hant-TW, nicht zh_TW oder Chinese. Ein ungültiger Tag wird unverändert gespeichert und kann von assistiven Technologien ignoriert werden. Die Engine validiert den Tag nur dann fail-fast, wenn der strikte Tagged-PDF-Modus aktiviert ist.
setKeywords() nimmt einen einzelnen String entgegen. Übergeben Sie durch Kommas getrennte Begriffe. Die Engine zerlegt kein PHP-Array für Sie.
Zusammenspiel mit Tagged PDF. Wenn Tagged PDF später aktiviert wird, bleibt eine zuvor explizit per setLanguage() gesetzte Sprache erhalten. Die strukturelle Sprache ist nur ein Fallback, wenn keine gesetzt wurde.
Datumsangaben werden von der Engine verwaltet. Zeitstempel für Erstellung und Änderung stammen aus der Engine-Uhr; der Reproduzierbarkeits-Harness fixiert sie. Deshalb ist das Profil structural und nicht bitwise.

Performance

Das Setzen von Metadaten ist eine Feldzuweisung in konstanter Zeit ohne Rendering-Kosten. Der Vorgang bleibt deutlich innerhalb des Budgets von 1000 ms / 64 MB.

Sicherheitshinweise

Metadaten werden im Klartext gespeichert und lassen sich leicht extrahieren. Legen Sie keine Geheimnisse, internen Bezeichner oder personenbezogenen Daten, die Sie nicht veröffentlichen würden, in die Felder Titel, Autor, Betreff, Schlüsselwörter oder Ersteller. Diese Felder werden mit der Datei weitergegeben und von Suchwerkzeugen indexiert. Bereinigen Sie die Metadaten, bevor Sie ein aus einer internen Vorlage abgeleitetes Dokument verteilen.

Konformität

Aussage	Spezifikation	Abschnitt
Metadaten sind allgemeine Informationen über ein Dokument.	ISO 32000-2	§14.3
Der Eintrag `Author` im Info-Dictionary ist in PDF 2.0 optional und veraltet.	ISO 32000-2	§14.3
An das Dokument kann ein XMP-Metadaten-Stream auf Dokumentebene angehängt werden.	ISO 32000-2	§14.3

NextPDF gibt die in den zitierten Klauseln beschriebenen Metadatenstrukturen aus. Es erhebt keinen Anspruch auf pauschale ISO 32000-2-Konformität.