Linearization: เอาต์พุต Fast Web View

ภาพรวมโดยย่อ

ไฟล์ Portable Document Format (PDF) แบบ linearized หรือที่เรียกว่า Fast Web View จะถูกจัดเรียงเพื่อให้โปรแกรมอ่านแสดงหน้าแรกได้ก่อนที่ไฟล์ทั้งหมดจะมาถึง ออบเจ็กต์ของหน้าแรก ส่วนย่อย cross-reference ของหน้าแรก และตาราง hint สำหรับหน้าที่เหลือทั้งหมดจะอยู่ใกล้ส่วนหน้าของไฟล์ NextPDF สร้างเค้าโครงนี้อย่างกำหนดได้แน่นอน: เอกสารเดียวกันจะสร้างชุดไบต์เดียวกันบนทุกโฮสต์ และผลลัพธ์ผ่าน qpdf --check-linearization

Linearization เป็นฟีเจอร์ของ Core หากต้องการใช้งาน ให้เปิดใช้บน Document เอนจินจะจัดการเค้าโครงแบบสามรอบ ดิกชันนารีพารามิเตอร์ linearization และตาราง hint ให้ครบถ้วน ส่วน LinearizationView ฝั่งอ่านจะแยกวิเคราะห์ดิกชันนารี linearization ในไฟล์ที่เสร็จสมบูรณ์ เพื่อให้ชั้นการขนส่งวางแผนการส่งมอบได้โดยไม่ต้องสร้างตรรกะของรูปแบบนี้ซ้ำ

การติดตั้ง

composer require nextpdf/core:^3

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

PDF มาตรฐานจะวางตาราง cross-reference ไว้ที่ส่วนท้าย ดังนั้นโปรแกรมอ่านจึงต้องดึงส่วนท้ายของไฟล์มาก่อนจึงจะแก้การอ้างอิงไปยังออบเจ็กต์ใด ๆ ได้ PDF แบบ linearized จะจัดไฟล์เป็นสองส่วน ส่วนแรกบรรจุดิกชันนารีพารามิเตอร์ linearization หน้าแรก และตาราง hint แบบ page-offset ส่วนที่สองบรรจุหน้าที่เหลือ โปรแกรมอ่านที่รองรับ Fast Web View สามารถเรนเดอร์หน้าแรกจากส่วนแรก จากนั้นใช้ตาราง hint เพื่อเข้าถึงหน้าถัด ๆ ไปได้โดยตรงขณะที่ไบต์ยังทยอยมาถึง ตามที่กำหนดไว้ใน ISO 32000-2 Annex F

NextPDF มีแบ็กเอนด์ให้เลือกสองแบบ แบ็กเอนด์ v2 ซึ่งเป็นค่าเริ่มต้นคือ linearizer แบบสามรอบที่สร้างเอาต์พุต ISO 32000-2 Annex F พร้อมตาราง hint แบบ page-offset ที่สอดคล้องตามข้อกำหนด และค่าความยาว /L ที่เท่ากับความยาวไบต์จริงของไฟล์ แบ็กเอนด์ v1 แบบเดิมยังคงมีอยู่เพื่อความเข้ากันได้ระดับไบต์กับเอกสารที่สร้างก่อน v2 โดยจะสร้างพารามิเตอร์ Annex F ที่ไม่สอดคล้องตามข้อกำหนด และต้องเลือกเปิดใช้เองเท่านั้น สำหรับงานใหม่ให้ใช้ค่าเริ่มต้น

รับประกันว่าเอาต์พุตกำหนดได้แน่นอน ตัวระบุไฟล์มาจาก digest ของเนื้อหา ไม่ได้มาจากแหล่งสุ่ม ดังนั้น enableLinearization() จึงเป็นฟังก์ชันบริสุทธิ์ของเอกสาร สิ่งนี้ช่วยให้การทดสอบ golden byte ตรึงเอาต์พุตได้ และช่วยให้ระบบปลายทางใช้แคชแบบ content-addressed หรือ ETag ที่เสถียรได้

การเปิดใช้งาน linearization

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 จะนำการตั้งค่าไปใช้เมื่อสร้างเอกสาร วิธีนี้เหมาะกับ pipeline ที่เลือกรูปแบบการส่งมอบไว้ล่วงหน้าแทนที่จะเรียกเมธอดบนเอกสารแต่ละฉบับ:

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() เดียวกัน ดังนั้นการป้องกันด้านความสอดคล้องด้านล่างจึงมีผลเหมือนกัน

การทำงานร่วมกันด้านความสอดคล้อง

Linearization ทำงานร่วมกับโปรไฟล์แบบ tagged และแบบ archival ได้ แต่ไม่สามารถใช้ร่วมกับฟีเจอร์ที่จะทำให้ตาราง hint ส่วนหน้าหรือลายเซ็นแบบ byte-range ของ PDF Advanced Electronic Signatures (PAdES) ใช้งานไม่ได้

ฟีเจอร์	การทำงานร่วมกัน
PDF/A, PDF/UA	ใช้ร่วมกันได้ v2 รักษาการกำหนดหมายเลขออบเจ็กต์ไว้ ดังนั้นโครงสร้างและการอ้างอิงแท็กจึงยังคงใช้งานได้
การเข้ารหัสลับ (AES-256, AES-GCM, public-key)	ใช้ร่วมกันไม่ได้ สตรีม hint จะถูกสร้างขึ้นในรูปแบบ plaintext ดังนั้นเอนจินจึงปฏิเสธการใช้คู่นี้ร่วมกัน
ลายเซ็น PAdES	ใช้ร่วมกันไม่ได้ การทำ linearization ใหม่จะเขียน byte offset ทับ และจะทำให้ /ByteRange ของลายเซ็นเสียหาย
การอัปเดตแบบ incremental	ใช้ร่วมกันไม่ได้ภายในการสร้างครั้งเดียว

การป้องกันนี้ทำงานทั้งสองทิศทางและไม่ขึ้นกับลำดับ การร้องขอการเข้ารหัสลับ (หรือลายเซ็น) บนเอกสารที่ถูกทำเครื่องหมายไว้สำหรับ linearization แล้วจะ throw ข้อยกเว้น การทำเครื่องหมายเอกสารที่เข้ารหัสลับไว้แล้ว (หรือลงลายเซ็นไว้แล้ว) สำหรับ linearization ก็จะ throw ข้อยกเว้นเช่นกัน ทั้งสองเส้นทางจะ throw 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.
}

การอ่านไฟล์แบบ linearized

LinearizationView แยกวิเคราะห์ดิกชันนารีพารามิเตอร์ linearization ที่ส่วนหน้าของ 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, ฟิลด์ดิกชันนารีแบบ public read-only	เสถียร	3.2.0

enableLinearization() จะ throw InvalidConfigException เมื่อมีการกำหนดค่าการเข้ารหัสลับหรือลายเซ็น PAdES ไว้แล้ว LinearizationView::fromPdf() จะคืนค่ามุมมองที่มีแฟล็ก isLinearized เป็น false สำหรับเอกสารที่ไม่มีดิกชันนารี linearization

ข้อจำกัด

• เอกสารแบบ linearized ไม่สามารถเข้ารหัสลับหรือลงลายเซ็นด้วย PAdES ไปพร้อมกันได้ เลือกอย่างใดอย่างหนึ่งต่อการสร้างหนึ่งครั้ง
• แบ็กเอนด์ v1 แบบเดิมจะสร้างพารามิเตอร์ Annex F ที่ไม่สอดคล้องตามข้อกำหนด และมีอยู่เพื่อความเข้ากันได้ระดับไบต์กับเอาต์พุตรุ่นเก่าเท่านั้น เกตตรวจความสอดคล้องจะทำงานกับ v2
• Fast Web View เป็นการปรับให้การส่งมอบมีประสิทธิภาพ ไม่ใช่ฟีเจอร์ด้านความปลอดภัยหรือการตรวจสอบความถูกต้อง โดยจะไม่เปลี่ยนแปลงเนื้อหาหน้าที่เรนเดอร์ออกมา