Ustawianie metadanych dokumentu (tytuł, autor, język)

W skrócie

Ustaw pola metadanych dokumentu w formacie Portable Document Format (PDF): tytuł, autora, temat, słowa kluczowe oraz twórcę. W tym samym przebiegu ustaw język dokumentu. Pola te trafiają do informacji o dokumencie oraz do metadanych na poziomie dokumentu. Czytniki PDF wyświetlają te dane w panelu „Properties”, a narzędzia wyszukiwania i katalogowania mogą je indeksować. Ten przepis jest zgodny z examples/16-metadata.php.

Instalacja

composer require nextpdf/core:^3

Omówienie koncepcyjne

Metadane to ogólne informacje o dokumencie (ISO 32000-2 §14.3). PDF 2.0 przechowuje je w dwóch miejscach: w starszym słowniku informacji o dokumencie oraz w strumieniu metadanych Extensible Metadata Platform (XMP) na poziomie dokumentu. W PDF 2.0 większość pól słownika informacji, w tym Author, jest jawnie opcjonalna i wycofana na rzecz XMP.

Settery cechy HasMetadata aktualizują model metadanych silnika, a moduł zapisujący generuje odpowiadające im wpisy. setLanguage() ustawia w katalogu pole /Lang, którego używają technologie wspomagające. Profil to structural, ponieważ dokument zawiera w przyczepce wpis /ID oraz datę metadanych. Końcowy etap normalizuje oba elementy przed porównaniem dwóch uruchomień.

Powierzchnia API

NextPDF\Core\Concerns\HasMetadata (Document korzysta z tej cechy):

setTitle(string $title): static
setAuthor(string $author): static
setSubject(string $subject): static
setKeywords(string $keywords): static
setCreator(string $creator): static
setLanguage(string $lang): static — znacznik Best Current Practice (BCP) 47 (en, zh-Hant-TW, ja)
isTaggedPdfEnabled(): bool — akcesor tylko do odczytu dla aktywnego trybu otagowanego

Przykład kodu — szybki start

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

Przykład kodu — produkcja

Poniższy pełny przykład odpowiada examples/16-metadata.php i zapisuje wynik do NEXTPDF_COOKBOOK_OUTPUT na potrzeby uprzęży testowej.

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

Oczekiwane dane wyjściowe:

Wrote document with metadata

Przypadki brzegowe i pułapki

PDF 2.0 wycofuje pola słownika Info. Wpis Author oraz pozostałe wpisy słownika informacji są opcjonalne i wycofane w PDF 2.0. Dla konsumentów PDF 2.0 miarodajnym źródłem metadanych jest strumień XMP. NextPDF generuje oba zestawy dla zachowania zgodności, dlatego nie zakładaj, że rygorystyczny czytnik PDF 2.0 udostępni pola słownika Info.
Język jest zgodny z BCP 47. Używaj zh-Hant-TW, a nie zh_TW ani Chinese. Nieprawidłowy znacznik zostaje zapisany dosłownie i może zostać zignorowany przez technologie wspomagające. Silnik weryfikuje znacznik w trybie fail-fast tylko wtedy, gdy włączony jest tryb ścisły otagowanego PDF.
setKeywords() przyjmuje pojedynczy ciąg znaków. Przekaż terminy rozdzielone przecinkami. Silnik nie rozdziela automatycznie tablicy PHP.
Interakcja z otagowanym PDF. Gdy otagowany PDF zostanie włączony później, jawne wywołanie setLanguage() wykonane wcześniej zostaje zachowane. Język strukturalny jest jedynie rozwiązaniem zapasowym, gdy wcześniej nie ustawiono żadnego języka.
Datami zarządza silnik. Znaczniki czasu utworzenia i modyfikacji pochodzą z zegara silnika, a uprząż powtarzalności je przypina. Dlatego profil to structural, a nie bitwise.

Wydajność

Ustawianie metadanych polega na przypisaniu pola w stałym czasie i nie wiąże się z żadnym kosztem renderowania. Mieści się z dużym zapasem w budżecie 1000 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Metadane są przechowywane jako zwykły tekst i łatwo je wyodrębnić. Nie umieszczaj w polach tytułu, autora, tematu, słów kluczowych ani twórcy sekretów, wewnętrznych identyfikatorów ani danych osobowych, które nie powinny być publiczne. Te pola podążają wraz z plikiem i są indeksowane przez narzędzia wyszukiwania. Wyczyść metadane przed rozpowszechnieniem dokumentu utworzonego na podstawie wewnętrznego szablonu.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Metadane to ogólne informacje o dokumencie.	ISO 32000-2	§14.3
Wpis `Author` w słowniku Info jest opcjonalny i wycofany w PDF 2.0.	ISO 32000-2	§14.3
Do dokumentu może zostać dołączony strumień metadanych XMP na poziomie dokumentu.	ISO 32000-2	§14.3

NextPDF generuje struktury metadanych opisane w przytoczonych klauzulach. Nie deklaruje całościowej zgodności z ISO 32000-2.