Doğrusallaştırma: Fast Web View çıkışı

Bir bakışta

Doğrusallaştırılmış bir Portable Document Format (PDF) dosyası, Fast Web View olarak da adlandırılır ve bir okuyucunun ilk sayfayı dosyanın tamamı gelmeden önce görüntüleyebileceği biçimde düzenlenir. İlk sayfanın nesneleri, çapraz başvuru alt bölümü ve diğer her sayfaya ait ipucu tablosu, dosyanın başına yakın bir konumda yer alır. NextPDF bu yerleşimi deterministik olarak üretir: aynı belge, her ana bilgisayarda aynı baytları oluşturur ve sonuç qpdf --check-linearization denetiminden geçer.

Doğrusallaştırma, bir Core özelliğidir. Kullanmak için Document üzerinde etkinleştirin; motor, üç geçişli yerleşimi, doğrusallaştırma parametre sözlüğünü ve ipucu tablosunu yönetir. Okuma tarafındaki LinearizationView, tamamlanmış bir dosyadaki doğrusallaştırma sözlüğünü ayrıştırır; böylece bir taşıma katmanı, biçimi yeniden uygulamaya gerek kalmadan teslimatı planlayabilir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Standart bir PDF, çapraz başvuru tablosunu sona yerleştirir; bu nedenle bir okuyucu, herhangi bir nesneyi çözümleyebilmek için önce dosyanın son kısmını almak zorundadır. Doğrusallaştırılmış bir PDF, dosyayı iki bölüme ayırır. İlk bölüm, doğrusallaştırma parametre sözlüğünü, ilk sayfayı ve sayfa ofseti ipucu tablosunu içerir. İkinci bölümde kalan sayfalar yer alır. Fast Web View’i destekleyen bir okuyucu, ilk bölümden birinci sayfayı oluşturabilir; ardından ISO 32000-2 Annex F’te tanımlandığı gibi, baytlar gelmeye devam ederken ipucu tablosunu kullanarak doğrudan sonraki herhangi bir sayfaya gidebilir.

NextPDF iki arka uç sağlar. Varsayılan v2 arka ucu, uyumlu bir sayfa ofseti ipucu tablosu ve dosyanın tam bayt uzunluğuna eşit bir /L uzunluğu içeren ISO 32000-2 Annex F çıktısı üreten üç geçişli bir doğrusallaştırıcıdır. v2 öncesinde üretilen belgelerle bayt uyumluluğu için eski bir v1 arka ucu bulunur; bu arka uç, uyumlu olmayan Annex F parametreleri üretir ve yalnızca isteğe bağlı olarak etkinleştirilir. Yeni çalışmalar için varsayılanı kullanın.

Determinizm garanti edilir. Dosya tanımlayıcısı rastgele bir kaynaktan değil, içerik özetinden gelir; bu nedenle enableLinearization(), belgenin saf bir işlevidir. Bu, golden bayt testlerinin çıktıyı sabitlemesine olanak tanır ve aşağı akış sistemlerinin içerik adresli bir önbellek ya da kararlı bir ETag kullanmasını sağlar.

Doğrusallaştırmayı etkinleştirme

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

Varsayılan arka uç v2’dir. Eski v1 arka ucunu kullanmak için önce useLegacyLinearizer() çağrısını yapın (her iki sıralama da çalışır):

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

Yapılandırma üzerinden

Bunu Config aracılığıyla da etkinleştirebilirsiniz. NextPDF, ayarı belgeyi oluştururken uygular; bu, teslimat biçimini her belge üzerinde bir yöntem çağırmak yerine baştan seçen işlem hatlarına uygundur:

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

Diğer Config seçenekleri gibi, withLinearization() da varsayılan olarak kapalıdır. Bu tercihi açıkça belirtmek için false geçirin. Bu şekilde oluşturulan bir belge, aynı enableLinearization() yolunu kullanır; bu nedenle aşağıdaki uygunluk korumaları aynı şekilde uygulanır.

Uygunluk etkileşimleri

Doğrusallaştırma, etiketli ve arşiv profilleriyle birlikte çalışır; ancak baştaki ipucu tablosunu ya da bir PDF Advanced Electronic Signatures (PAdES) bayt aralığı imzasını geçersiz kılacak özelliklerle birlikte kullanılamaz.

Özellik	Etkileşim
PDF/A, PDF/UA	Birlikte kullanılabilir. v2, nesne numaralandırmasını korur; böylece yapı ve etiket başvuruları geçerli kalır.
Şifreleme (AES-256, AES-GCM, açık anahtar)	Karşılıklı olarak dışlayıcı. Aksi durumda ipucu akışı düz metin olarak üretilirdi; bu nedenle motor bu ikiliyi reddeder.
PAdES imzaları	Karşılıklı olarak dışlayıcı. Yeniden doğrusallaştırma, bayt ofsetlerini yeniden yazar ve bir imzanın /ByteRange değerini bozardı.
Artımlı güncellemeler	Tek bir derleme içinde karşılıklı olarak dışlayıcıdır.

Bu koruma çift yönlüdür ve sıralamadan bağımsızdır. Doğrusallaştırma için zaten işaretlenmiş bir belgede şifreleme (veya imza) istenmesi bir hata fırlatır. Zaten şifrelenmiş (veya imzalanmış) bir belgenin doğrusallaştırma için işaretlenmesi de bir hata fırlatır. Her iki yol da InvalidConfigException fırlatır.

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

Doğrusallaştırılmış bir dosyayı okuma

LinearizationView, tamamlanmış bir PDF’nin başındaki doğrusallaştırma parametre sözlüğünü ayrıştırır. Teslimatı planlayan bir taşıma katmanı için desteklenen tek giriş noktasıdır; çağıranlar, sözlük ayrıştırıcısını asla yeniden uygulamaz.

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 yüzeyi

Tür	Çeşit	Önemli üyeler	Kararlılık	Bu sürümden beri
Document	sınıf	enableLinearization(): static, useLegacyLinearizer(): static	kararlı	3.2.0
Config	sınıf	withLinearization(bool $linearize = true): self	kararlı	6.1.0
LinearizationView	sınıf	fromPdf(string): self, lengthMatches(int): bool, genel, salt okunur sözlük alanları	kararlı	3.2.0

enableLinearization(), şifreleme veya bir PAdES imzası zaten yapılandırılmışsa InvalidConfigException fırlatır. LinearizationView::fromPdf(), doğrusallaştırma sözlüğü bulunmayan bir belge için isLinearized bayrağı false olan bir görünüm döndürür.

Sınırlamalar

• Doğrusallaştırılmış bir belge aynı zamanda şifrelenemez veya PAdES ile imzalanamaz. Her derleme için bunlardan birini seçin.
• Eski v1 arka ucu, uyumlu olmayan Annex F parametreleri üretir ve yalnızca eski çıktılarla bayt uyumluluğu için bulunur. Uygunluk denetimi v2 üzerinde çalışır.
• Fast Web View, bir güvenlik veya doğrulama özelliği değil, bir teslimat iyileştirmesidir. İşlenen sayfa içeriğini değiştirmez.