Establecer los metadatos del documento (título, autor, idioma)

De un vistazo

Establece los campos de metadatos del documento —título, autor, asunto, palabras clave y creador— junto con el idioma del documento. Estos campos rellenan la información del documento y los metadatos a nivel de documento. Los lectores de PDF muestran estos datos en el panel «Propiedades», y las herramientas de búsqueda y catalogación los indexan. Esta receta sigue examples/16-metadata.php.

Instalación

composer require nextpdf/core:^3

Resumen conceptual

Los metadatos son información general sobre un documento (ISO 32000-2 §14.3). PDF 2.0 los conserva en dos lugares: el antiguo diccionario de información del documento y un flujo de metadatos XMP a nivel de documento. En PDF 2.0, la mayoría de los campos del diccionario de información, incluido Author, son explícitamente opcionales y están obsoletos en favor de XMP.

Los setters de HasMetadata rellenan el modelo de metadatos del motor, y el escritor emite las entradas correspondientes. setLanguage() establece el /Lang del catálogo, que utiliza la tecnología de asistencia. El perfil es structural porque el documento incluye un /ID en el tráiler y una fecha de metadatos; el paso posterior normaliza ambos antes de comparar dos ejecuciones.

Superficie de la API

NextPDF\Core\Concerns\HasMetadata (incorporado en 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 — etiqueta BCP-47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — accesor de solo lectura del modo etiquetado activo

Ejemplo de código — Inicio 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";

Ejemplo de código — Producción

El ejemplo completo siguiente refleja examples/16-metadata.php. Escribe en NEXTPDF_COOKBOOK_OUTPUT para el arnés de pruebas.

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

Salida esperada:

Wrote document with metadata

Casos límite y trampas

PDF 2.0 deja obsoletos los campos del diccionario Info. Author y las demás entradas del diccionario de información son opcionales y están obsoletas en PDF 2.0. Para un consumidor de PDF 2.0, el flujo XMP contiene los metadatos autoritativos. NextPDF emite ambos por compatibilidad, así que no asumir que un lector estricto de PDF 2.0 mostrará los campos del diccionario Info.
El idioma es BCP-47. Usar zh-Hant-TW, no zh_TW ni Chinese. Una etiqueta no válida se almacena tal cual, y la tecnología de asistencia puede ignorarla. El motor solo valida la etiqueta con error inmediato cuando el modo estricto de PDF etiquetado está habilitado.
setKeywords() recibe una sola cadena. Pasar términos separados por comas. El motor no divide por ti un array de PHP.
Interacción con el PDF etiquetado. Cuando el PDF etiquetado se habilita posteriormente, se conserva una llamada explícita previa a setLanguage(). El idioma estructural solo actúa como valor de reserva cuando no se ha establecido ninguno.
Las fechas las gestiona el motor. Las marcas de tiempo de creación y modificación provienen del reloj del motor, y el arnés de reproducibilidad las fija. Por eso el perfil es structural, no bitwise.

Rendimiento

Establecer los metadatos es una asignación de campos en tiempo constante, sin costo de renderizado. Se mantiene holgadamente dentro del presupuesto de 1000 ms / 64 MB.

Notas de seguridad

Los metadatos se almacenan en texto plano y se pueden extraer fácilmente. No incluir secretos, identificadores internos ni datos personales que no se publicarían en los campos de título, autor, asunto, palabras clave o creador. Esos campos viajan con el archivo y las herramientas de búsqueda los indexan. Depurar los metadatos antes de distribuir un documento derivado de una plantilla interna.

Conformidad

Declaración	Especificación	Cláusula
Los metadatos son información general sobre un documento.	ISO 32000-2	§14.3
La entrada `Author` del diccionario Info es opcional y está obsoleta en PDF 2.0.	ISO 32000-2	§14.3
Puede adjuntarse al documento un flujo de metadatos XMP a nivel de documento.	ISO 32000-2	§14.3

NextPDF emite las estructuras de metadatos descritas por las cláusulas citadas. No declara conformidad general con ISO 32000-2.