Documentmetadata instellen (titel, auteur, taal)

In een oogopslag

Stel de metadatavelden van het Portable Document Format (PDF) in: titel, auteur, onderwerp, trefwoorden en maker. Stel in dezelfde bewerking ook de documenttaal in. Deze velden vullen de documentinformatie en de metadata op documentniveau. PDF-lezers tonen deze gegevens in het paneel ‘Eigenschappen’, en zoek- en catalogiseringstools kunnen ze indexeren. Dit recept volgt examples/16-metadata.php.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Metadata is algemene informatie over een document (ISO 32000-2 §14.3). PDF 2.0 slaat die informatie op twee plaatsen op: de verouderde document information dictionary en een metadatastream van het Extensible Metadata Platform (XMP) op documentniveau. In PDF 2.0 zijn de meeste velden van de information dictionary, waaronder Author, expliciet optioneel en afgeschaft ten gunste van XMP.

De setters van HasMetadata werken het metadatamodel van de engine bij; de writer schrijft de bijbehorende vermeldingen weg. setLanguage() stelt de catalogus-/Lang in, die door ondersteunende technologie wordt gebruikt. Het profiel is structural omdat het document een trailer-/ID en een metadatadatum bevat. De nabewerking normaliseert beide voordat twee runs worden vergeleken.

API-oppervlak

NextPDF\Core\Concerns\HasMetadata (gebruikt 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 — Best Current Practice (BCP) 47-tag (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — alleen-lezen accessor voor de actieve tagged-modus

Codevoorbeeld — Snel aan de slag

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

Codevoorbeeld — Productie

Het volledige voorbeeld hieronder volgt examples/16-metadata.php en schrijft voor de harness naar 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";

Verwachte uitvoer:

Wrote document with metadata

Randgevallen en valkuilen

In PDF 2.0 zijn de velden van de Info dictionary afgeschaft. Author en de overige vermeldingen van de information dictionary zijn optioneel en afgeschaft in PDF 2.0. Voor een PDF 2.0-consument vormt de XMP-stream de gezaghebbende metadata. NextPDF schrijft beide weg voor compatibiliteit, dus ga er niet van uit dat een strikte PDF 2.0-lezer de Info-velden zichtbaar maakt.
De taal gebruikt BCP 47. Gebruik zh-Hant-TW, niet zh_TW of Chinese. Een ongeldige tag wordt letterlijk opgeslagen en kan door ondersteunende technologie worden genegeerd. De engine valideert de tag alleen met fail-fast-gedrag wanneer de strikte modus voor tagged PDF is ingeschakeld.
setKeywords() verwacht één string. Geef door komma’s gescheiden termen door. De engine splitst geen PHP-array voor je.
Interactie met tagged PDF. Wanneer tagged PDF later wordt ingeschakeld, blijft een expliciete setLanguage()-aanroep die eerder is gedaan, behouden. De structurele taal is slechts een terugvaloptie wanneer er geen taal is ingesteld.
Datums worden door de engine beheerd. Tijdstempels voor aanmaak en wijziging komen van de klok van de engine; de reproduceerbaarheidsharness legt ze vast. Daarom is het profiel structural in plaats van bitwise.

Prestaties

Het instellen van metadata is een veldtoewijzing in constante tijd en brengt geen weergavekosten met zich mee. Het blijft ruim binnen het budget van 1000 ms / 64 MB.

Beveiligingsopmerkingen

Metadata wordt in leesbare tekst opgeslagen en is eenvoudig te extraheren. Plaats geen geheimen, interne identifiers of persoonsgegevens die je niet zou publiceren in de velden voor titel, auteur, onderwerp, trefwoorden of maker. Die velden reizen mee met het bestand en worden door zoektools geïndexeerd. Verwijder metadata voordat je een document distribueert dat is afgeleid van een interne sjabloon.

Conformiteit

Bewering	Specificatie	Clausule
Metadata is algemene informatie over een document.	ISO 32000-2	§14.3
De vermelding `Author` in de Info dictionary is optioneel en afgeschaft in PDF 2.0.	ISO 32000-2	§14.3
Aan het document kan een XMP-metadatastream op documentniveau worden gekoppeld.	ISO 32000-2	§14.3

NextPDF schrijft de metadatastructuren weg die door de aangehaalde clausules worden beschreven. Het claimt geen algehele ISO 32000-2-conformiteit.