Linearisasi: keluaran Fast Web View

Sekilas pandang

Berkas Portable Document Format (PDF) terlinearisasi, yang juga disebut Fast Web View, ditata agar pembaca dapat menampilkan halaman pertama sebelum seluruh berkas selesai diterima. Objek halaman pertama, subbagian cross-reference-nya, dan tabel hint untuk halaman lainnya ditempatkan di dekat awal berkas. NextPDF menghasilkan tata letak ini secara deterministik: dokumen yang sama menghasilkan bita yang sama di setiap host, dan keluarannya lolos qpdf --check-linearization.

Linearisasi adalah fitur Core. Untuk menggunakannya, aktifkan pada Document; mesin akan menangani tata letak tiga-lintasan, kamus parameter linearisasi, dan tabel hint. LinearizationView di sisi-baca mengurai kamus linearisasi dari berkas yang sudah selesai, sehingga transport dapat merencanakan pengiriman tanpa mengimplementasikan ulang formatnya.

Pemasangan

composer require nextpdf/core:^3

Gambaran konseptual

PDF standar menempatkan tabel cross-reference di bagian akhir, sehingga pembaca harus mengambil ekor berkas sebelum dapat me-resolve objek apa pun. PDF terlinearisasi menyusun berkas ke dalam dua bagian. Bagian pertama berisi kamus parameter linearisasi, halaman pertama, dan tabel hint page-offset. Bagian kedua berisi halaman-halaman selebihnya. Pembaca yang mendukung Fast Web View dapat merender halaman pertama dari bagian pertama, lalu menggunakan tabel hint untuk langsung melompat ke halaman mana pun setelahnya saat bita terus berdatangan, sebagaimana didefinisikan oleh ISO 32000-2 Annex F.

NextPDF menyediakan dua backend. Backend v2 standar adalah linearizer tiga-lintasan yang menghasilkan keluaran ISO 32000-2 Annex F dengan tabel hint page-offset yang konforman dan panjang /L yang persis sama dengan panjang bita berkas. Backend v1 lawas tetap tersedia demi kompatibilitas bita dengan dokumen yang dibuat sebelum v2; backend ini menghasilkan parameter Annex F yang tidak konforman dan hanya tersedia secara opt-in. Untuk pekerjaan baru, gunakan backend standar.

Determinisme dijamin. Pengidentifikasi berkas berasal dari digest konten, bukan dari sumber acak, sehingga enableLinearization() merupakan fungsi murni dari dokumen. Hal ini memungkinkan golden byte test menyematkan keluaran, sekaligus memungkinkan sistem hilir menggunakan cache beralamat-konten atau ETag yang stabil.

Mengaktifkan linearisasi

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();

Backend standar adalah v2. Untuk menggunakan backend v1 lawas, panggil useLegacyLinearizer() terlebih dahulu (urutan mana pun berfungsi):

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

Dari konfigurasi

Anda juga dapat mengaktifkannya melalui Config. NextPDF menerapkan pengaturan tersebut saat membangun dokumen; pendekatan ini cocok untuk pipeline yang memilih format pengiriman di awal alih-alih memanggil metode pada setiap dokumen:

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

Seperti opsi Config lainnya, withLinearization() nonaktif secara baku. Berikan false untuk membuat pilihan itu eksplisit. Dokumen yang dibangun dengan cara ini menggunakan jalur enableLinearization() yang sama, sehingga penjaga konformansi di bawah ini berlaku identik.

Interaksi konformansi

Linearisasi bekerja dengan profil tagged dan arsip, tetapi saling eksklusif dengan fitur yang akan membatalkan tabel hint awal atau tanda tangan byte-range PDF Advanced Electronic Signatures (PAdES).

Fitur	Interaksi
PDF/A, PDF/UA	Dapat digabungkan. v2 mempertahankan penomoran objek, sehingga referensi struktur dan tag tetap valid.
Enkripsi (AES-256, AES-GCM, public-key)	Saling eksklusif. Aliran hint akan dihasilkan sebagai plaintext, sehingga mesin menolak kombinasi tersebut.
Tanda tangan PAdES	Saling eksklusif. Linearisasi ulang menulis ulang offset bita dan akan merusak /ByteRange dalam tanda tangan.
Pembaruan inkremental	Saling eksklusif dalam satu build.

Mekanisme penjaga ini berlaku dua arah dan tidak bergantung pada urutan. Meminta enkripsi (atau tanda tangan) pada dokumen yang sudah ditandai untuk linearisasi akan melemparkan exception. Menandai dokumen yang sudah dienkripsi (atau sudah ditandatangani) untuk linearisasi juga akan melemparkan exception. Kedua jalur tersebut melemparkan 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.
}

Membaca berkas terlinearisasi

LinearizationView mengurai kamus parameter linearisasi di bagian awal PDF yang sudah selesai. Ini adalah satu-satunya titik masuk yang didukung bagi transport yang merencanakan pengiriman; pemanggil tidak perlu mengimplementasikan ulang pengurai kamus.

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;
}

Permukaan API

Tipe	Jenis	Anggota utama	Stabilitas	Sejak
Document	class	enableLinearization(): static, useLegacyLinearizer(): static	stable	3.2.0
Config	class	withLinearization(bool $linearize = true): self	stable	6.1.0
LinearizationView	class	fromPdf(string): self, lengthMatches(int): bool, field kamus publik read-only	stable	3.2.0

enableLinearization() melemparkan InvalidConfigException ketika enkripsi atau tanda tangan PAdES sudah dikonfigurasi. LinearizationView::fromPdf() mengembalikan tampilan dengan flag isLinearized bernilai false untuk dokumen tanpa kamus linearisasi.

Keterbatasan

• Dokumen terlinearisasi tidak dapat sekaligus dienkripsi atau ditandatangani dengan PAdES. Pilih salah satu per build.
• Backend v1 lawas menghasilkan parameter Annex F yang tidak konforman dan hanya ada demi kompatibilitas bita dengan keluaran yang lebih lama. Gerbang konformansi dijalankan terhadap v2.
• Fast Web View adalah optimasi pengiriman, bukan fitur keamanan atau validasi. Fitur ini tidak mengubah konten halaman yang dirender.