Linearyzacja: dane wyjściowe w trybie Fast Web View

W skrócie

Zlinearyzowany plik Portable Document Format (PDF), nazywany także Fast Web View, jest ułożony tak, aby czytnik mógł wyświetlić pierwszą stronę, zanim zostanie pobrany cały plik. Obiekty pierwszej strony, podsekcja odsyłaczy tej strony oraz tablica podpowiedzi dla każdej kolejnej strony znajdują się blisko początku pliku. NextPDF generuje ten układ deterministycznie: ten sam dokument daje te same bajty na każdym hoście, a wynik pozytywnie przechodzi qpdf --check-linearization.

Linearyzacja jest funkcją Core. Aby jej użyć, włącz ją w obiekcie Document; silnik realizuje trzyprzebiegowy układ, słownik parametrów linearyzacji oraz tablicę podpowiedzi. Działający po stronie odczytu LinearizationView analizuje słownik linearyzacji w gotowym pliku, dzięki czemu warstwa transportowa może zaplanować dostarczanie bez ponownego implementowania formatu.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Standardowy plik PDF przechowuje tablicę odsyłaczy na końcu, więc czytnik musi pobrać końcową część pliku, zanim będzie mógł rozwiązać jakikolwiek obiekt. Zlinearyzowany plik PDF dzieli plik na dwie części. Pierwsza część zawiera słownik parametrów linearyzacji, pierwszą stronę oraz tablicę podpowiedzi przesunięć stron. Druga część zawiera pozostałe strony. Czytnik obsługujący Fast Web View może wyrenderować pierwszą stronę z pierwszej części, a następnie użyć tablicy podpowiedzi, aby przejść bezpośrednio do dowolnej kolejnej strony w miarę napływania bajtów, zgodnie z definicją w załączniku F normy ISO 32000-2.

NextPDF udostępnia dwa zaplecza. Domyślne zaplecze v2 to trzyprzebiegowy linearyzator, który wytwarza dane wyjściowe zgodne z załącznikiem F normy ISO 32000-2, ze zgodną tablicą podpowiedzi przesunięć stron oraz długością /L równą dokładnej długości pliku w bajtach. Starsze zaplecze v1 pozostaje dostępne dla zgodności bajt po bajcie z dokumentami utworzonymi przed wersją v2; generuje parametry niezgodne z załącznikiem F i jest dostępne wyłącznie po jawnym włączeniu. W nowych projektach używaj wartości domyślnej.

Determinizm jest gwarantowany. Identyfikator pliku jest wyprowadzany ze skrótu treści, a nie ze źródła losowego, więc enableLinearization() jest czystą funkcją dokumentu. Dzięki temu testy porównujące bajty ze wzorcem mogą utrwalić dane wyjściowe, a systemy dalszego przetwarzania mogą korzystać z pamięci podręcznej adresowanej treścią lub ze stabilnego ETag.

Włączanie linearyzacji

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

Domyślne zaplecze to v2. Aby użyć starszego zaplecza v1, wywołaj najpierw useLegacyLinearizer() (kolejność nie ma znaczenia):

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

Z konfiguracji

Możesz ją także włączyć za pośrednictwem Config. NextPDF stosuje to ustawienie podczas budowania dokumentu, co dobrze pasuje do potoków, które z góry wybierają format dostarczania, zamiast wywoływać metodę dla każdego dokumentu:

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

Podobnie jak inne opcje Config, withLinearization() jest domyślnie wyłączona. Przekaż false, aby uczynić ten wybór jawnym. Dokument zbudowany w ten sposób korzysta z tej samej ścieżki enableLinearization(), więc opisane poniżej zabezpieczenia zgodności mają identyczne zastosowanie.

Interakcje zgodności

Linearyzacja współpracuje z profilami tagowanymi i archiwalnymi, ale wzajemnie wyklucza się z funkcjami, które unieważniłyby tablicę podpowiedzi umieszczoną na początku pliku albo podpis PDF Advanced Electronic Signatures (PAdES) oparty na zakresie bajtów.

Funkcja	Interakcja
PDF/A, PDF/UA	Łączą się. v2 zachowuje numerację obiektów, więc odwołania do struktury i tagów pozostają prawidłowe.
Szyfrowanie (AES-256, AES-GCM, klucz publiczny)	Wzajemnie się wykluczają. Strumień podpowiedzi zostałby wygenerowany w postaci tekstu jawnego, więc silnik odrzuca tę parę.
Podpisy PAdES	Wzajemnie się wykluczają. Ponowna linearyzacja zmienia przesunięcia bajtów i naruszyłaby /ByteRange podpisu.
Aktualizacje przyrostowe	Wzajemnie się wykluczają w ramach jednej kompilacji.

Zabezpieczenie jest dwukierunkowe i niezależne od kolejności. Żądanie szyfrowania (lub podpisu) dla dokumentu już oznaczonego do linearyzacji powoduje zgłoszenie wyjątku. Oznaczenie do linearyzacji dokumentu już zaszyfrowanego (lub już podpisanego) również powoduje zgłoszenie wyjątku. W obu ścieżkach zgłaszany jest 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.
}

Odczytywanie zlinearyzowanego pliku

LinearizationView analizuje słownik parametrów linearyzacji znajdujący się na początku gotowego pliku PDF. To jedyny obsługiwany punkt wejścia dla warstwy transportowej planującej dostarczanie; kod wywołujący nigdy nie implementuje ponownie parsera słownika.

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

Powierzchnia API

Typ	Rodzaj	Kluczowe składowe	Stabilność	Od wersji
Document	klasa	enableLinearization(): static, useLegacyLinearizer(): static	stabilny	3.2.0
Config	klasa	withLinearization(bool $linearize = true): self	stabilny	6.1.0
LinearizationView	klasa	fromPdf(string): self, lengthMatches(int): bool, publiczne pola słownika przeznaczone tylko do odczytu	stabilny	3.2.0

enableLinearization() zgłasza InvalidConfigException, gdy wcześniej skonfigurowano szyfrowanie lub podpis PAdES. LinearizationView::fromPdf() zwraca widok, którego flaga isLinearized ma wartość false dla dokumentu bez słownika linearyzacji.

Ograniczenia

• Zlinearyzowany dokument nie może być jednocześnie zaszyfrowany ani podpisany za pomocą PAdES. Wybierz jedno w ramach jednej kompilacji.
• Starsze zaplecze v1 generuje parametry niezgodne z załącznikiem F i istnieje wyłącznie dla zgodności bajt po bajcie ze starszymi danymi wyjściowymi. Bramka zgodności działa względem v2.
• Fast Web View to optymalizacja dostarczania, a nie funkcja zabezpieczeń ani walidacji. Nie zmienia wyrenderowanej treści strony.