Mengatur metadata dokumen (judul, penulis, bahasa)

Sekilas pandang

Tetapkan ruas metadata Portable Document Format (PDF): judul, penulis, subjek, kata kunci, dan pembuat. Tetapkan bahasa dokumen dalam alur yang sama. Ruas-ruas ini mengisi informasi dokumen dan metadata tingkat dokumen. Pembaca PDF menampilkan data ini di panel “Properties”, dan alat pencarian serta pengatalogan dapat mengindeksnya. Resep ini mengikuti examples/16-metadata.php.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Metadata adalah informasi umum tentang sebuah dokumen (ISO 32000-2 §14.3). PDF 2.0 menyimpannya di dua tempat: kamus informasi dokumen lawas dan aliran metadata Extensible Metadata Platform (XMP) tingkat dokumen. Pada PDF 2.0, sebagian besar ruas kamus informasi, termasuk Author, secara eksplisit opsional dan usang sehingga XMP lebih diutamakan.

Setter HasMetadata memperbarui model metadata mesin, dan komponen penulis menghasilkan entri yang sesuai. setLanguage() menetapkan /Lang pada katalog, yang digunakan oleh teknologi bantu. Profil bersifat structural karena dokumen membawa trailer /ID dan tanggal metadata. Tahap pascaproses menormalkan keduanya sebelum membandingkan dua proses.

Permukaan API

NextPDF\Core\Concerns\HasMetadata (digabungkan ke dalam 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 — pengakses hanya-baca untuk mode tagged yang aktif

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Contoh lengkap di bawah ini mengikuti examples/16-metadata.php dan menulis keluaran ke NEXTPDF_COOKBOOK_OUTPUT untuk 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";

Keluaran yang diharapkan:

Wrote document with metadata

Kasus tepi & jebakan

PDF 2.0 mengusangkan ruas kamus Info. Author dan entri kamus informasi lainnya bersifat opsional dan usang pada PDF 2.0. Bagi konsumen PDF 2.0, aliran XMP adalah sumber metadata otoritatif. NextPDF menghasilkan keduanya demi kompatibilitas, jadi jangan berasumsi bahwa pembaca PDF 2.0 yang ketat akan menampilkan ruas Info.
Bahasa mengikuti BCP 47. Gunakan zh-Hant-TW, bukan zh_TW atau Chinese. Tag yang tidak valid disimpan apa adanya dan mungkin diabaikan oleh teknologi bantu. Mesin memvalidasi tag dengan perilaku fail-fast hanya ketika mode tagged-PDF ketat diaktifkan.
setKeywords() menerima satu string tunggal. Berikan istilah yang dipisahkan koma. Mesin tidak akan memecah array PHP untuk Anda.
Interaksi dengan tagged-PDF. Ketika tagged PDF diaktifkan belakangan, panggilan setLanguage() eksplisit yang dilakukan sebelumnya tetap dipertahankan. Bahasa struktural hanya menjadi cadangan ketika belum ada yang diatur.
Tanggal dikelola oleh mesin. Stempel waktu pembuatan dan modifikasi berasal dari jam mesin, dan harness keterulangan menyematkan keduanya. Itulah sebabnya profil bersifat structural alih-alih bitwise.

Kinerja

Mengatur metadata adalah penetapan ruas dengan waktu konstan dan tidak menambah biaya rendering. Operasi ini tetap jauh di bawah anggaran 1000 ms / 64 MB.

Catatan keamanan

Metadata disimpan dalam teks polos dan mudah diekstrak. Jangan menempatkan rahasia, pengenal internal, atau data pribadi yang tidak akan Anda publikasikan ke dalam ruas judul, penulis, subjek, kata kunci, atau pembuat. Ruas-ruas tersebut terbawa bersama berkas dan diindeks oleh alat pencarian. Bersihkan metadata sebelum Anda mendistribusikan dokumen yang berasal dari templat internal.

Kesesuaian

Pernyataan	Spesifikasi	Klausul
Metadata adalah informasi umum tentang sebuah dokumen.	ISO 32000-2	§14.3
Entri `Author` pada kamus Info bersifat opsional dan usang pada PDF 2.0.	ISO 32000-2	§14.3
Aliran metadata XMP tingkat dokumen dapat dilampirkan ke dokumen.	ISO 32000-2	§14.3

NextPDF menghasilkan struktur metadata yang dijelaskan oleh klausul yang dikutip. Ini tidak menyatakan kesesuaian ISO 32000-2 secara menyeluruh.