Impostare i metadati del documento (titolo, autore, lingua)

In sintesi

Impostare i campi dei metadati del documento — titolo, autore, oggetto, parole chiave e autore della creazione — insieme alla lingua del documento. Questi campi popolano le informazioni del documento e i metadati a livello di documento. I lettori PDF mostrano questi dati nel pannello «Proprietà», mentre gli strumenti di ricerca e catalogazione li indicizzano. Questa ricetta si basa su examples/16-metadata.php.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

I metadati sono informazioni generali su un documento (ISO 32000-2 §14.3). PDF 2.0 li archivia in due posizioni: il dizionario legacy delle informazioni del documento e un flusso di metadati XMP a livello di documento. In PDF 2.0, la maggior parte dei campi del dizionario delle informazioni, incluso Author, è esplicitamente facoltativa e deprecata a favore di XMP.

I setter di HasMetadata popolano il modello di metadati del motore e il writer emette le voci corrispondenti. setLanguage() imposta il /Lang del catalogo, usato dalle tecnologie assistive. Il profilo è structural perché il documento contiene un /ID nel trailer e una data dei metadati; il post-pass normalizza entrambi prima di confrontare due esecuzioni.

Superficie API

NextPDF\Core\Concerns\HasMetadata (incluso 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 — tag BCP-47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — accessor di sola lettura per la modalità tagged attiva

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

L’esempio completo riportato di seguito rispecchia examples/16-metadata.php. Scrive su NEXTPDF_COOKBOOK_OUTPUT per l’harness.

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

Output previsto:

Wrote document with metadata

Casi limite e insidie

In PDF 2.0 i campi del dizionario Info sono deprecati. Author e le altre voci del dizionario delle informazioni sono facoltative e deprecate in PDF 2.0. Per un consumer PDF 2.0, il flusso XMP costituisce i metadati autorevoli. NextPDF emette entrambi per compatibilità, pertanto non va dato per scontato che un lettore PDF 2.0 rigoroso esponga i campi Info.
La lingua è BCP-47. Usare zh-Hant-TW, non zh_TW o Chinese. Un tag non valido viene memorizzato testualmente e può essere ignorato dalle tecnologie assistive. Il motore convalida il tag secondo un approccio fail-fast solo quando è abilitata la modalità strict del PDF tagged.
setKeywords() accetta una singola stringa. Passare termini separati da virgole. Il motore non suddivide automaticamente un array PHP.
Interazione con il PDF tagged. Quando il PDF tagged viene abilitato in un secondo momento, una chiamata esplicita a setLanguage() effettuata in precedenza viene conservata. La lingua strutturale funge da fallback solo quando non ne è stata impostata alcuna.
Le date sono gestite dal motore. I timestamp di creazione e modifica provengono dal clock del motore e l’harness di riproducibilità li fissa. Ecco perché il profilo è structural anziché bitwise.

Prestazioni

L’impostazione dei metadati è un’assegnazione di campi a costo costante, senza costi di rendering. Rientra ampiamente nel budget di 1000 ms / 64 MB.

Note sulla sicurezza

I metadati vengono memorizzati in chiaro e sono facilmente estraibili. Non vanno inseriti segreti, identificatori interni o dati personali che non si pubblicherebbero nei campi titolo, autore, oggetto, parole chiave o autore della creazione. Tali campi viaggiano insieme al file e vengono indicizzati dagli strumenti di ricerca. Ripulire i metadati prima di distribuire un documento derivato da un modello interno.

Conformità

Dichiarazione	Specifica	Clausola
I metadati sono informazioni generali su un documento.	ISO 32000-2	§14.3
La voce `Author` del dizionario Info è facoltativa e deprecata in PDF 2.0.	ISO 32000-2	§14.3
Al documento può essere allegato un flusso di metadati XMP a livello di documento.	ISO 32000-2	§14.3

NextPDF emette le strutture di metadati descritte dalle clausole citate. Non dichiara una conformità generale a ISO 32000-2.