Définir les métadonnées du document (titre, auteur, langue)

En bref

Définis les métadonnées du document — titre, auteur, sujet, mots-clés, créateur — ainsi que sa langue. Ces champs alimentent les informations du document et les métadonnées de niveau document. Les lecteurs PDF affichent ces données dans leur panneau « Propriétés » ; les outils de recherche et de catalogage les indexent. Cette recette reprend examples/16-metadata.php.

Installation

composer require nextpdf/core:^3

Aperçu conceptuel

Les métadonnées sont des informations générales sur un document (ISO 32000-2 §14.3). PDF 2.0 les stocke à deux endroits : le dictionnaire d’information du document hérité et un flux de métadonnées XMP au niveau du document. En PDF 2.0, la plupart des champs du dictionnaire d’information, dont Author, sont explicitement facultatifs et dépréciés au profit de XMP.

Les setters de HasMetadata alimentent le modèle de métadonnées du moteur, puis le composant d’écriture émet les entrées correspondantes. setLanguage() définit l’entrée /Lang du catalogue, utilisée par les technologies d’assistance. Le profil est structural, car le document contient un /ID de trailer et une date de métadonnées ; le post-traitement normalise les deux avant de comparer deux exécutions.

Surface de l’API

NextPDF\Core\Concerns\HasMetadata (intégré à 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 — balise BCP-47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — accesseur en lecture seule pour le mode tagged actif

Exemple de code — Démarrage rapide

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

Exemple de code — Production

L’exemple complet ci-dessous reflète examples/16-metadata.php. Il écrit dans NEXTPDF_COOKBOOK_OUTPUT, comme l’attend le harnais.

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

Sortie attendue :

Wrote document with metadata

Cas limites et pièges

PDF 2.0 déprécie les champs du dictionnaire Info. Author et les autres entrées du dictionnaire d’information sont facultatifs et dépréciés en PDF 2.0. Pour un consommateur PDF 2.0, le flux XMP est la source de métadonnées qui fait autorité. NextPDF émet les deux pour la compatibilité ; ne pars donc pas du principe qu’un lecteur PDF 2.0 strict affichera les champs Info.
La langue est en BCP-47. Utilise zh-Hant-TW, pas zh_TW ni Chinese. Une balise invalide est stockée telle quelle et peut être ignorée par les technologies d’assistance. Le moteur ne valide la balise en fail-fast que lorsque le mode strict tagged-PDF est activé.
setKeywords() prend une seule chaîne. Passe des termes séparés par des virgules. Le moteur ne découpe pas un tableau PHP à ta place.
Interaction avec le tagged-PDF. Lorsque le tagged PDF est activé plus tard, un appel explicite préalable à setLanguage() est préservé. La langue structurelle n’est un repli que lorsque aucune n’a été définie.
Les dates sont gérées par le moteur. Les horodatages de création et de modification proviennent de l’horloge du moteur, et le harnais de reproductibilité les fige. C’est pour cela que le profil est structural plutôt que bitwise.

Performance

Définir les métadonnées revient à affecter des champs en temps constant, sans coût de rendu. Cela reste largement sous le budget de 1000 ms / 64 Mo.

Notes de sécurité

Les métadonnées sont stockées en clair et très faciles à extraire. Ne place pas de secrets, d’identifiants internes ni de données personnelles que tu ne publierais pas dans les champs titre, auteur, sujet, mots-clés ou créateur. Ces champs circulent avec le fichier et sont indexés par les outils de recherche. Nettoie les métadonnées avant de distribuer un document dérivé d’un modèle interne.

Conformité

Énoncé	Spéc	Clause
Les métadonnées sont des informations générales sur un document.	ISO 32000-2	§14.3
L’entrée `Author` du dictionnaire Info est facultative et dépréciée en PDF 2.0.	ISO 32000-2	§14.3
Un flux de métadonnées XMP au niveau du document peut être attaché au document.	ISO 32000-2	§14.3

NextPDF émet les structures de métadonnées décrites par les clauses citées. Il ne revendique pas une conformité générale à ISO 32000-2.