Đặt siêu dữ liệu của tài liệu (tiêu đề, tác giả, ngôn ngữ)

Tổng quan nhanh

Đặt các trường siêu dữ liệu Portable Document Format (PDF): tiêu đề, tác giả, chủ đề, từ khóa và người tạo. Đặt ngôn ngữ của tài liệu trong cùng luồng xử lý đó. Các trường này được ghi vào thông tin tài liệu và siêu dữ liệu ở cấp tài liệu. Trình đọc PDF hiển thị dữ liệu này trong bảng “Properties” của chúng, còn các công cụ tìm kiếm và lập danh mục có thể lập chỉ mục dữ liệu đó. Công thức này bám sát examples/16-metadata.php.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Siêu dữ liệu là thông tin chung về một tài liệu (ISO 32000-2 §14.3). PDF 2.0 lưu siêu dữ liệu ở hai nơi: từ điển thông tin tài liệu kiểu cũ và một luồng siêu dữ liệu Extensible Metadata Platform (XMP) ở cấp tài liệu. Trong PDF 2.0, hầu hết các trường của từ điển thông tin, bao gồm Author, được xác định là tùy chọn và không còn được khuyến nghị nhằm ưu tiên XMP.

Các setter của HasMetadata cập nhật mô hình siêu dữ liệu của engine, và bộ ghi xuất ra các mục tương ứng. setLanguage() đặt mục /Lang trong catalog để công nghệ hỗ trợ sử dụng. Hồ sơ này là structural vì tài liệu có một /ID trong trailer và một ngày siêu dữ liệu. Bước hậu xử lý chuẩn hóa cả hai trước khi so sánh giữa hai lần chạy.

Bề mặt API

NextPDF\Core\Concerns\HasMetadata (được trộn vào 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 — thẻ Best Current Practice (BCP) 47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — accessor chỉ đọc cho chế độ tagged đang hoạt động

Ví dụ mã — bắt đầu nhanh

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

Ví dụ mã — Production

Ví dụ đầy đủ bên dưới phản ánh examples/16-metadata.php và ghi vào NEXTPDF_COOKBOOK_OUTPUT cho bộ kiểm thử.

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

Kết quả mong đợi:

Wrote document with metadata

Trường hợp đặc biệt và lưu ý

PDF 2.0 không còn khuyến nghị các trường của từ điển Info. Author và các mục khác của từ điển thông tin là tùy chọn và không còn được khuyến nghị trong PDF 2.0. Với trình đọc PDF 2.0, luồng XMP mới là siêu dữ liệu chính thức. NextPDF xuất ra cả hai để tương thích, vì vậy đừng giả định rằng một trình đọc PDF 2.0 nghiêm ngặt sẽ hiển thị các trường Info.
Ngôn ngữ tuân theo BCP-47. Dùng zh-Hant-TW, không dùng zh_TW hay Chinese. Một thẻ không hợp lệ sẽ được lưu nguyên văn và có thể bị công nghệ hỗ trợ bỏ qua. Engine chỉ xác thực thẻ và báo lỗi ngay khi chế độ nghiêm ngặt của tagged PDF được bật.
setKeywords() nhận một chuỗi đơn. Truyền các từ khóa cách nhau bằng dấu phẩy. Engine không tự tách mảng PHP thay cho bạn.
Tương tác với tagged PDF. Khi tagged PDF được bật về sau, lệnh gọi setLanguage() tường minh trước đó sẽ được giữ lại. Ngôn ngữ cấu trúc chỉ là phương án dự phòng khi chưa có ngôn ngữ nào được đặt.
Ngày tháng do engine quản lý. Dấu thời gian tạo và sửa đổi lấy từ đồng hồ của engine, và bộ kiểm thử khả năng tái lập sẽ cố định chúng. Vì vậy hồ sơ này là structural thay vì bitwise.

Hiệu năng

Đặt siêu dữ liệu là thao tác gán trường với thời gian không đổi và không tốn chi phí kết xuất. Thao tác này dễ dàng nằm trong giới hạn 1000 ms / 64 MB.

Lưu ý bảo mật

Siêu dữ liệu được lưu dưới dạng văn bản thuần và rất dễ trích xuất. Đừng đặt bí mật, định danh nội bộ hay dữ liệu cá nhân mà bạn không muốn công bố vào các trường tiêu đề, tác giả, chủ đề, từ khóa hoặc người tạo. Các trường đó đi kèm tệp và được các công cụ tìm kiếm lập chỉ mục. Hãy làm sạch siêu dữ liệu trước khi phân phối tài liệu được tạo từ mẫu nội bộ.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Siêu dữ liệu là thông tin chung về một tài liệu.	ISO 32000-2	§14.3
Mục `Author` của từ điển Info là tùy chọn và không còn được khuyến nghị trong PDF 2.0.	ISO 32000-2	§14.3
Một luồng siêu dữ liệu XMP ở cấp tài liệu có thể được đính kèm vào tài liệu.	ISO 32000-2	§14.3

NextPDF xuất ra các cấu trúc siêu dữ liệu được mô tả trong các điều khoản đã trích dẫn. Điều này không khẳng định việc tuân thủ toàn diện ISO 32000-2.