الخطية: مخرجات العرض السريع على الويب

لمحة سريعة

يُرتَّب ملف ⁨PDF⁩ الخطي، المعروف أيضًا باسم العرض السريع على الويب، بحيث يستطيع القارئ عرض الصفحة الأولى قبل وصول الملف كاملًا. توضع كائنات الصفحة الأولى، وقسم الإحالة المرجعية الفرعي الخاص بها، وجدول التلميحات لكل صفحة أخرى، قرب بداية الملف. يُصدِر ⁨NextPDF⁩ هذا التخطيط بصورة حتمية: ينتج المستند نفسه البايتات نفسها على كل مضيف، وتجتاز النتيجة qpdf --check-linearization.

الخطية ميزة من ميزات ⁨Core.⁩ لاستخدامها، فعِّلها على Document؛ وسيتولى المحرك التخطيط ثلاثي المرور، وقاموس معاملات الخطية، وجدول التلميحات. يحلِّل LinearizationView من جانب القراءة قاموس الخطية في ملف مكتمل، وبذلك يستطيع نظام النقل تخطيط التسليم دون إعادة تنفيذ الصيغة.

التثبيت

composer require nextpdf/core:^3

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

يضع ملف ⁨PDF⁩ القياسي جدول الإحالة المرجعية في النهاية، لذلك يجب على القارئ جلب نهاية الملف قبل أن يتمكن من حلِّ أي كائن. أما ملف ⁨PDF⁩ الخطي فينظِّم الملف في جزأين. يحتوي الجزء الأول على قاموس معاملات الخطية، والصفحة الأولى، وجدول تلميحات إزاحة الصفحات. ويحتوي الجزء الثاني على الصفحات المتبقية. يستطيع القارئ الذي يدعم العرض السريع على الويب تصيير الصفحة الأولى من الجزء الأول، ثم استخدام جدول التلميحات للانتقال مباشرة إلى أي صفحة لاحقة بينما يستمر وصول البايتات، وفق ما يحدده الملحق ⁨F⁩ من ⁨ISO 32000-2.⁩

يوفِّر ⁨NextPDF⁩ واجهتين خلفيتين. الواجهة الخلفية الافتراضية ⁨v2⁩ هي مخطِّط خطي ثلاثي المرور ينتج مخرجات الملحق ⁨F⁩ من ⁨ISO 32000-2⁩ مع جدول تلميحات إزاحة الصفحات مطابق للمواصفة، وطول /L يساوي طول البايتات الدقيق للملف. وتبقى الواجهة الخلفية القديمة ⁨v1⁩ متاحة للتوافق على مستوى البايتات مع المستندات المنتَجة قبل ⁨v2⁩؛ وهي تُصدِر معاملات ملحق ⁨F⁩ غير مطابقة للمواصفة، ويجب تفعيلها يدويًا فقط. استخدم الواجهة الافتراضية في أي عمل جديد.

الحتمية مضمونة. يأتي معرِّف الملف من ملخَّص المحتوى، لا من مصدر عشوائي، لذلك تكون enableLinearization() دالة محضة للمستند. يتيح ذلك لاختبارات البايتات المرجعية تثبيت المخرجات، كما يتيح للأنظمة اللاحقة استخدام ذاكرة تخزين مؤقت معنونة بالمحتوى أو ETag مستقر.

تفعيل الخطية

examples/linearization/enable.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->writeHtml('<h1>Quarterly report</h1>');
$document->enableLinearization();

// Deterministic: the same document always produces the same bytes.
$pdf = $document->output();

الواجهة الخلفية الافتراضية هي ⁨v2.⁩ لاستخدام الواجهة الخلفية القديمة ⁨v1⁩، استدعِ useLegacyLinearizer() أولًا (كلا الترتيبين صالح):

$document->useLegacyLinearizer();
$document->enableLinearization();

من الإعدادات

يمكنك أيضًا تفعيلها عبر Config. يطبِّق ⁨NextPDF⁩ الإعداد عند بناء المستند، وهذا يناسب خطوط الأنابيب التي تختار صيغة التسليم مسبقًا بدلًا من استدعاء طريقة على كل مستند:

use NextPDF\Core\Config;
use NextPDF\Core\Document;

$config   = (new Config())->withLinearization();
$document = Document::createStandalone($config);
$document->writeHtml('<h1>Quarterly report</h1>');

$pdf = $document->output(); // linearized output

كما هو الحال مع خيارات Config الأخرى، تكون withLinearization() معطَّلة افتراضيًا. مرِّر false لجعل هذا الاختيار صريحًا. يستخدم المستند المبني بهذه الطريقة مسار enableLinearization() نفسه، لذلك تنطبق ضمانات المطابقة أدناه بصورة مطابقة.

تفاعلات المطابقة

تعمل الخطية مع الملفات الموسومة والأرشيفية، لكنها متعارضة حصريًا مع الميزات التي تُبطِل جدول التلميحات المقدَّم أو توقيع نطاق البايتات لتوقيعات ⁨PDF⁩ الإلكترونية المتقدمة (⁨PAdES⁩).

الميزة	التفاعل
⁨PDF/A⁩، ⁨PDF/UA⁩	قابلة للتركيب. تحافظ ⁨v2⁩ على ترقيم الكائنات، لذلك تبقى مراجع البنية والوسوم صالحة.
التشفير (⁨AES-256⁩، ⁨AES-GCM⁩، المفتاح العام)	متعارضان حصريًا. سيُصدَر دفق التلميحات كنص صريح، لذا يرفض المحرك هذا الاقتران.
توقيعات ⁨PAdES⁩	متعارضان حصريًا. تعيد الخطية كتابة إزاحات البايتات، وستكسر /ByteRange الخاص بالتوقيع.
التحديثات التزايدية	متعارضان حصريًا في بناء واحد.

الضمانة ثنائية الاتجاه ومستقلة عن الترتيب. طلب التشفير (أو توقيع) على مستند موسوم بالفعل للخطية يطلق استثناءً. كما أن وسم مستند مشفَّر بالفعل (أو موقَّع بالفعل) للخطية يطلق استثناءً أيضًا. يطلق كلا المسارين InvalidConfigException.

use NextPDF\Exception\InvalidConfigException;

$document->setEncryption('user-pw', 'owner-pw'); // (userPassword, ownerPassword)

try {
    $document->enableLinearization(); // rejected — encryption is already configured
} catch (InvalidConfigException $e) {
    // Linearization and encryption cannot be combined on one document.
}

قراءة ملف خطي

يحلِّل LinearizationView قاموس معاملات الخطية في مقدمة ملف ⁨PDF⁩ مكتمل. وهو نقطة الدخول المدعومة الوحيدة لنظام نقل يخطِّط التسليم؛ يجب ألا يعيد المستدعون أبدًا تنفيذ محلِّل القاموس.

examples/linearization/inspect.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Writer\Linearization\LinearizationView;

$view = LinearizationView::fromPdf($pdf);

if ($view->isLinearized) {
    // Plan, e.g., a first-page byte range from the parsed dictionary fields:
    // file length, first-page object number, main cross-reference offset,
    // hint-table offset and length, first-page end offset, page count.
    $firstPageEnd = $view->firstPageEndOffset;
}

سطح ⁨API⁩

النوع	الصنف	الأعضاء الرئيسيون	الاستقرار	منذ
Document	⁨class⁩	enableLinearization(): static، useLegacyLinearizer(): static	مستقر	3.2.0
Config	⁨class⁩	withLinearization(bool $linearize = true): self	مستقر	6.1.0
LinearizationView	⁨class⁩	fromPdf(string): self، lengthMatches(int): bool، حقول قاموس عامة للقراءة فقط	مستقر	3.2.0

يطلق enableLinearization() استثناء InvalidConfigException عندما يكون التشفير أو توقيع ⁨PAdES⁩ مهيَّأً بالفعل. يُرجِع LinearizationView::fromPdf() عرضًا تكون فيه الراية isLinearized مساوية لـ false إذا كان المستند لا يحتوي على قاموس خطية.

القيود

• لا يمكن تشفير مستند خطي أو توقيعه بـ ⁨PAdES⁩ أيضًا. اختر واحدًا لكل بناء.
• تُصدِر الواجهة الخلفية القديمة ⁨v1⁩ معاملات ملحق ⁨F⁩ غير مطابقة للمواصفة، وهي موجودة فقط للتوافق على مستوى البايتات مع المخرجات الأقدم. تعمل بوابة المطابقة على ⁨v2.⁩
• العرض السريع على الويب تحسين للتسليم، وليس ميزة أمان أو تحقُّق. وهو لا يغيِّر محتوى الصفحة المُصيَّر.