ตั้งค่าเมตาดาตาของเอกสาร (title, author, language)

ภาพรวมโดยสังเขป

ตั้งค่าฟิลด์เมตาดาตาของ Portable Document Format (PDF) ได้แก่ title, author, subject, keywords และ creator พร้อมตั้งค่าภาษาของเอกสารในขั้นตอนเดียวกัน ฟิลด์เหล่านี้จะเติมข้อมูลลงใน document information และเมตาดาตาระดับเอกสาร โปรแกรมอ่าน PDF จะแสดงข้อมูลนี้ในแผง “Properties” และเครื่องมือค้นหากับเครื่องมือจัดทำแคตตาล็อกสามารถนำข้อมูลนี้ไปจัดทำดัชนีได้ สูตรนี้ใช้ไฟล์ examples/16-metadata.php เป็นต้นแบบ

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

เมตาดาตาคือข้อมูลทั่วไปเกี่ยวกับเอกสาร (ISO 32000-2 §14.3) PDF 2.0 จัดเก็บข้อมูลนี้ไว้สองตำแหน่ง ได้แก่ document information dictionary แบบดั้งเดิม และสตรีมเมตาดาตา Extensible Metadata Platform (XMP) ระดับเอกสาร ใน PDF 2.0 ฟิลด์ส่วนใหญ่ของ information-dictionary รวมถึง Author ถูกระบุไว้อย่างชัดเจนว่า เป็นทางเลือกและเลิกใช้แล้ว โดยให้ใช้ XMP แทน

เซตเตอร์ของ HasMetadata จะอัปเดตโมเดลเมตาดาตาของเอนจิน และตัวเขียนจะเขียนรายการที่สอดคล้องกันออกมา setLanguage() จะตั้งค่า /Lang ในแคตตาล็อก ซึ่งเป็นค่าที่เทคโนโลยีสิ่งอำนวยความสะดวกนำไปใช้ โปรไฟล์กำหนดเป็น structural เนื่องจากเอกสารมี /ID ใน trailer และวันที่ของเมตาดาตา การประมวลผลภายหลัง (post-pass) จะปรับทั้งสองค่าให้เป็นมาตรฐานก่อนเปรียบเทียบการรันสองครั้ง

ส่วนการเรียกใช้ API

NextPDF\Core\Concerns\HasMetadata (ผสานเข้าใน 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 — แท็กตาม Best Current Practice (BCP) 47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — แอ็กเซสเซอร์แบบอ่านอย่างเดียวสำหรับโหมด tagged ที่เปิดใช้งานอยู่

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

ตัวอย่างโค้ด — สำหรับใช้งานจริง

ตัวอย่างฉบับเต็มด้านล่างสอดคล้องกับ examples/16-metadata.php และเขียนผลลัพธ์ไปยัง NEXTPDF_COOKBOOK_OUTPUT สำหรับ 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";

ผลลัพธ์ที่คาดหวัง:

Wrote document with metadata

กรณีขอบและข้อควรระวัง

PDF 2.0 เลิกใช้ฟิลด์ของ Info dictionary Author และรายการอื่นๆ ของ information-dictionary เป็นทางเลือกและเลิกใช้แล้วใน PDF 2.0 สำหรับผู้บริโภค PDF 2.0 สตรีม XMP คือเมตาดาตาที่มีผลใช้งาน NextPDF เขียนออกมาทั้งสองรูปแบบเพื่อความเข้ากันได้ ดังนั้นอย่าสมมติว่าโปรแกรมอ่าน PDF 2.0 แบบเข้มงวดจะแสดงฟิลด์ Info ออกมา
ภาษาใช้รูปแบบ BCP-47 ใช้ zh-Hant-TW ไม่ใช่ zh_TW หรือ Chinese แท็กที่ไม่ถูกต้องจะถูกจัดเก็บตามที่ระบุไว้ทุกประการ และอาจถูกเทคโนโลยีสิ่งอำนวยความสะดวกละเลย เอนจินจะตรวจสอบความถูกต้องของแท็กด้วยพฤติกรรม fail-fast เฉพาะเมื่อเปิดใช้งานโหมดเข้มงวดของ tagged-PDF เท่านั้น
setKeywords() รับสตริงเดียว ส่งคำที่คั่นด้วยจุลภาค เอนจินจะไม่แยกอาร์เรย์ PHP ให้
การโต้ตอบกับ Tagged-PDF เมื่อเปิดใช้งาน tagged PDF ในภายหลัง การเรียก setLanguage() อย่างชัดเจนที่ทำไว้ก่อนหน้านั้นจะยังคงอยู่ ภาษาเชิงโครงสร้างเป็นเพียงค่าตัวสำรองเมื่อไม่มีการตั้งค่าภาษาไว้
วันที่ถูกจัดการโดยเอนจิน ไทม์สแตมป์การสร้างและการแก้ไขมาจากนาฬิกาของเอนจิน และ harness สำหรับการทำซ้ำได้จะตรึงค่าเหล่านี้ไว้ ด้วยเหตุนี้โปรไฟล์จึงเป็น structural แทนที่จะเป็น bitwise

ประสิทธิภาพ

การตั้งค่าเมตาดาตาเป็นการกำหนดค่าฟิลด์ที่ใช้เวลาคงที่และไม่มีต้นทุนด้านการเรนเดอร์ จึงอยู่ภายในงบประมาณ 1000 ms / 64 MB อย่างสบาย

หมายเหตุด้านความปลอดภัย

เมตาดาตาถูกจัดเก็บเป็นข้อความธรรมดาและดึงออกมาได้ง่าย ห้ามใส่ข้อมูลลับ ตัวระบุภายใน หรือข้อมูลส่วนบุคคลที่ไม่ต้องการเผยแพร่ลงในฟิลด์ title, author, subject, keywords หรือ creator ฟิลด์เหล่านั้นจะติดไปกับไฟล์และถูกเครื่องมือค้นหาจัดทำดัชนี ให้ล้างเมตาดาตาก่อนแจกจ่ายเอกสารที่สร้างจากเทมเพลตภายใน

ความสอดคล้อง

ข้อความ	ข้อกำหนด	ข้อ
เมตาดาตาคือข้อมูลทั่วไปเกี่ยวกับเอกสาร	ISO 32000-2	§14.3
รายการ `Author` ของ Info dictionary เป็นทางเลือกและเลิกใช้แล้วใน PDF 2.0	ISO 32000-2	§14.3
สตรีมเมตาดาตา XMP ระดับเอกสารอาจถูกแนบเข้ากับเอกสาร	ISO 32000-2	§14.3

NextPDF เขียนโครงสร้างเมตาดาตาตามที่อธิบายไว้ในข้อที่อ้างถึง โดยไม่ได้ยืนยันความสอดคล้องกับ ISO 32000-2 แบบครอบคลุมทั้งหมด