ضبط بيانات المستند الوصفية (العنوان، المؤلف، اللغة)

لمحة سريعة

عيّن حقول البيانات الوصفية لمستند ⁨PDF⁩: العنوان، والمؤلف، والموضوع، والكلمات المفتاحية، والمنشئ. واضبط لغة المستند ضمن تدفق العمل نفسه. تملأ هذه الحقول معلومات المستند وبياناته الوصفية على مستوى المستند. تعرض قارئات ⁨PDF⁩ هذه البيانات في لوحة “⁨Properties⁩”، كما تستطيع أدوات البحث والفهرسة فهرستها. تتبع هذه الوصفة المثال examples/16-metadata.php.

التثبيت

composer require nextpdf/core:^3

نظرة عامة مفاهيمية

البيانات الوصفية هي معلومات عامة عن المستند (⁨ISO 32000-2⁩ §14.3). يخزّنها ⁨PDF 2.0⁩ في موضعين: قاموس معلومات المستند القديم، ودفق بيانات وصفية على مستوى المستند لمنصة البيانات الوصفية القابلة للتوسعة (⁨XMP⁩). في ⁨PDF 2.0⁩، صُنّفت معظم حقول قاموس المعلومات، بما في ذلك Author، صراحةً على أنها اختيارية ومهملة لصالح ⁨XMP⁩.

تحدّث دوال الضبط في HasMetadata نموذج البيانات الوصفية للمحرك، ثم يُصدِر الكاتب المُدخلات المطابقة. تعيّن setLanguage() قيمة /Lang في الكتالوج، وتستخدمها التقنيات المساعِدة. ملف قابلية إعادة الإنتاج هو structural لأن المستند يحمل قيمة /ID في المُذيّل وتاريخًا للبيانات الوصفية. تُسوّي خطوة ما بعد المعالجة كليهما قبل مقارنة عمليتي تشغيل.

واجهة ⁨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 — وسم لغة وفق أفضل ممارسة حالية (⁨BCP⁩) 47 (en، zh-Hant-TW، ja)
• isTaggedPdfEnabled(): bool — دالة وصول للقراءة فقط إلى الوضع الموسوم النشط

نموذج برمجي — بداية سريعة

<?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 لاستخدامه في بيئة الاختبار.

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

الحالات الحدّية والمزالق

• تُعد حقول قاموس ⁨Info⁩ مهملة في ⁨PDF 2.0⁩. Author ومُدخلات قاموس المعلومات الأخرى اختيارية ومهملة في ⁨PDF 2.0⁩. لدى مستهلك ⁨PDF 2.0⁩، يكون دفق ⁨XMP⁩ هو البيانات الوصفية المرجعية. يُصدِر ⁨NextPDF⁩ كليهما لأغراض التوافق، لذا لا تفترض أن قارئ ⁨PDF 2.0⁩ الصارم سيُظهر حقول ⁨Info⁩.
• وسم اللغة بصيغة ⁨BCP 47⁩. استخدم zh-Hant-TW، وليس zh_TW أو Chinese. يُخزَّن الوسم غير الصالح حرفيًا، وقد تتجاهله التقنيات المساعِدة. لا يتحقق المحرك من صحة الوسم بسلوك الفشل السريع إلا عند تفعيل الوضع الصارم لـ ⁨PDF⁩ الموسوم.
• تأخذ setKeywords() سلسلة نصية واحدة. مرّر مصطلحات مفصولة بفواصل. لا يتولى المحرك تقسيم مصفوفة ⁨PHP⁩ نيابةً عنك.
• التفاعل مع ⁨PDF⁩ الموسوم. إذا فعّلت ⁨PDF⁩ الموسوم لاحقًا، يُحفظ استدعاء setLanguage() الصريح الذي أُجري أولًا. لا تكون اللغة البنيوية إلا بديلًا احتياطيًا عند عدم تعيين أي لغة.
• يدير المحرك التواريخ. تأتي طوابع وقت الإنشاء والتعديل من ساعة المحرك، وتثبّتها بيئة اختبار قابلية إعادة الإنتاج. ولهذا يكون ملف قابلية إعادة الإنتاج هو structural لا bitwise.

الأداء

تعيين البيانات الوصفية عملية إسناد حقل بزمن ثابت ولا تترتب عليها أي كلفة عرض. وتبقى ضمن ميزانية 1000 ⁨ms⁩ / 64 ⁨MB⁩ بهامش واسع.

ملاحظات أمنية

تُخزَّن البيانات الوصفية كنص صريح ويسهل استخراجها. لا تضع أسرارًا أو معرّفات داخلية أو بيانات شخصية لا ترغب في نشرها ضمن حقول العنوان أو المؤلف أو الموضوع أو الكلمات المفتاحية أو المنشئ. تنتقل هذه الحقول مع الملف، وتفهرسها أدوات البحث. نظّف البيانات الوصفية قبل توزيع مستند مشتق من قالب داخلي.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
البيانات الوصفية هي معلومات عامة عن المستند.	⁨ISO 32000-2⁩	§14.3
مُدخل Author في قاموس ⁨Info⁩ اختياري ومهمل في ⁨PDF 2.0⁩.	⁨ISO 32000-2⁩	§14.3
يجوز إرفاق دفق بيانات وصفية ⁨XMP⁩ على مستوى المستند بالمستند.	⁨ISO 32000-2⁩	§14.3

يُصدِر ⁨NextPDF⁩ بُنى البيانات الوصفية الموصوفة في البنود المُستشهَد بها. ولا يدّعي مطابقة شاملة لـ ⁨ISO 32000-2⁩.

انظر أيضًا

• وحدة البيانات الوصفية
• تعيين تفضيلات العارض
• التشفير مع الأذونات