Definir os metadados do documento (título, autor, idioma)

Visão geral

Defina os campos de metadados do Portable Document Format (PDF): título, autor, assunto, palavras-chave e criador. No mesmo fluxo, defina também o idioma do documento. Esses campos preenchem as informações do documento e os metadados em nível de documento. Leitores de PDF exibem esses dados no painel “Propriedades”, e ferramentas de busca e catalogação podem indexá-los. Esta receita segue examples/16-metadata.php.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Metadados são informações gerais sobre um documento (ISO 32000-2 §14.3). O PDF 2.0 os armazena em dois locais: o dicionário legado de informações do documento e um stream (fluxo) de metadados Extensible Metadata Platform (XMP) em nível de documento. No PDF 2.0, a maioria dos campos do dicionário de informações, incluindo Author, é explicitamente opcional e obsoleta em favor do XMP.

Os setters de HasMetadata atualizam o modelo de metadados do mecanismo, e o gravador emite as entradas correspondentes. setLanguage() define o /Lang do catálogo, usado pela tecnologia assistiva. O perfil é structural porque o documento contém um /ID no trailer e uma data de metadados. O pós-processamento normaliza ambos antes de comparar duas execuções.

Superfície da API

NextPDF\Core\Concerns\HasMetadata (incorporado em 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 Best Current Practice (BCP) 47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — acessor somente leitura para o modo tagged ativo

Exemplo de código — Início rápido

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

Exemplo de código — Produção

O exemplo completo abaixo espelha examples/16-metadata.php e grava em NEXTPDF_COOKBOOK_OUTPUT para uso pelo 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";

Saída esperada:

Wrote document with metadata

Casos extremos e pegadinhas

O PDF 2.0 torna obsoletos os campos do dicionário Info. Author e as outras entradas do dicionário de informações são opcionais e obsoletas no PDF 2.0. Para um consumidor de PDF 2.0, o stream (fluxo) XMP é a fonte oficial dos metadados. O NextPDF emite ambos por compatibilidade, então não presuma que um leitor estrito de PDF 2.0 exibirá os campos Info.
O idioma segue BCP-47. Use zh-Hant-TW, não zh_TW ou Chinese. Uma tag inválida é armazenada literalmente e pode ser ignorada pela tecnologia assistiva. O mecanismo só valida a tag com comportamento fail-fast quando o modo estrito de PDF tagged está habilitado.
setKeywords() recebe uma única string. Passe os termos separados por vírgulas. O mecanismo não divide um array PHP por você.
Interação com PDF tagged. Quando o PDF tagged é habilitado posteriormente, uma chamada explícita de setLanguage() feita antes é preservada. O idioma estrutural é apenas um fallback quando nenhum foi definido.
As datas são gerenciadas pelo mecanismo. Os carimbos de data/hora de criação e modificação vêm do relógio do mecanismo, e o harness de reprodutibilidade os fixa. É por isso que o perfil é structural em vez de bitwise.

Desempenho

Definir metadados é uma atribuição de campo em tempo constante e não tem custo de renderização. A operação fica bem dentro do orçamento de 1000 ms / 64 MB.

Notas de segurança

Os metadados são armazenados em texto puro e são fáceis de extrair. Não coloque segredos, identificadores internos ou dados pessoais que você não publicaria nos campos de título, autor, assunto, palavras-chave ou criador. Esses campos acompanham o arquivo e são indexados por ferramentas de busca. Limpe os metadados antes de distribuir um documento derivado de um modelo interno.

Conformidade

Declaração	Especificação	Cláusula
Metadados são informações gerais sobre um documento.	ISO 32000-2	§14.3
A entrada `Author` do dicionário Info é opcional e obsoleta no PDF 2.0.	ISO 32000-2	§14.3
Um stream (fluxo) de metadados XMP em nível de documento pode ser anexado ao documento.	ISO 32000-2	§14.3

O NextPDF emite as estruturas de metadados descritas pelas cláusulas citadas. Ele não declara conformidade total com a ISO 32000-2.