Linearisatie: uitvoer voor Fast Web View

In het kort

Een gelineariseerd Portable Document Format (PDF)-bestand, ook wel Fast Web View genoemd, is zo ingedeeld dat een lezer de eerste pagina kan weergeven voordat het volledige bestand is binnengekomen. De objecten van de eerste pagina, de bijbehorende kruisverwijzingssubsectie en de hinttabel voor alle andere pagina’s staan vooraan in het bestand. NextPDF genereert deze indeling deterministisch: hetzelfde document levert op elke host dezelfde bytes op, en het resultaat doorstaat qpdf --check-linearization.

Linearisatie is een Core-functie. Om de functie te gebruiken, schakelt u deze in op het Document; de engine verzorgt de driefasige indeling, het linearisatieparameterwoordenboek en de hinttabel. De leeszijdige LinearizationView ontleedt het linearisatiewoordenboek in een voltooid bestand, zodat een transportlaag de levering kan plannen zonder het formaat zelf opnieuw te implementeren.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Een standaard-PDF-bestand plaatst de kruisverwijzingstabel aan het einde, waardoor een lezer eerst het achterste deel van het bestand moet ophalen voordat die een object kan oplossen. Een gelineariseerde PDF deelt het bestand op in twee delen. Het eerste deel bevat het linearisatieparameterwoordenboek, de eerste pagina en de page-offset hinttabel. Het tweede deel bevat de overige pagina’s. Een lezer die Fast Web View ondersteunt, kan pagina één uit het eerste deel weergeven en daarna met de hinttabel direct naar elke latere pagina springen naarmate er meer bytes binnenkomen, zoals gedefinieerd in ISO 32000-2 bijlage F.

NextPDF biedt twee backends. De standaard-v2-backend is een driefasige linearizer die uitvoer volgens ISO 32000-2 bijlage F produceert met een conforme page-offset hinttabel en een /L-lengte die gelijk is aan de exacte bytelengte van het bestand. Een verouderde v1-backend blijft beschikbaar voor bytecompatibiliteit met documenten die vóór v2 zijn gemaakt; deze genereert niet-conforme bijlage F-parameters en kan uitsluitend expliciet worden ingeschakeld. Gebruik voor nieuw werk de standaardbackend.

Determinisme is gegarandeerd. De bestandsidentifier wordt afgeleid uit de content-digest en niet uit een willekeurige bron, zodat enableLinearization() een pure functie van het document is. Daardoor kunnen golden-byte-tests de uitvoer vastleggen en kunnen downstream-systemen een content-addressed cache of een stabiele ETag gebruiken.

Linearisatie inschakelen

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

De standaardbackend is v2. Als u de verouderde v1-backend wilt gebruiken, roept u eerst useLegacyLinearizer() aan (beide aanroepvolgorden werken):

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

Vanuit de configuratie

U kunt linearisatie ook inschakelen via Config. NextPDF past de instelling toe bij het opbouwen van het document, wat goed past bij pipelines die het leveringsformaat vooraf kiezen in plaats van per document een methode aan te roepen:

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

Net als andere Config-opties staat withLinearization() standaard uit. Geef false door om die keuze expliciet te maken. Een document dat u op deze manier opbouwt, gebruikt hetzelfde enableLinearization()-pad, zodat de conformiteitscontroles hieronder op dezelfde manier gelden.

Conformiteitsinteracties

Linearisatie werkt samen met de getagde en archiefprofielen, maar sluit functies uit die de vooraan geplaatste hinttabel of een byte-range-handtekening van PDF Advanced Electronic Signatures (PAdES) ongeldig zouden maken.

Functie	Interactie
PDF/A, PDF/UA	Combineerbaar. v2 behoudt de objectnummering, zodat structuur- en tagverwijzingen geldig blijven.
Versleuteling (AES-256, AES-GCM, publieke sleutel)	Wederzijds uitsluitend. De hint-stream zou als platte tekst worden uitgevoerd, dus de engine weigert de combinatie.
PAdES-handtekeningen	Wederzijds uitsluitend. Herlinearisatie herschrijft byte-offsets en zou de /ByteRange van een handtekening breken.
Incrementele updates	Wederzijds uitsluitend binnen één build.

De controle is bidirectioneel en volgorde-onafhankelijk. Versleuteling (of een handtekening) aanvragen voor een document dat al voor linearisatie is gemarkeerd, resulteert in een uitzondering. Een reeds versleuteld (of reeds ondertekend) document voor linearisatie markeren, resulteert eveneens in een uitzondering. In beide gevallen wordt InvalidConfigException gegooid.

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

Een gelineariseerd bestand lezen

LinearizationView ontleedt het linearisatieparameterwoordenboek vooraan in een voltooide PDF. Het is het enige ondersteunde startpunt voor een transportlaag die de levering plant; aanroepers implementeren de woordenboekparser nooit opnieuw.

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-oppervlak

Type	Soort	Belangrijkste leden	Stabiliteit	Sinds
Document	class	enableLinearization(): static, useLegacyLinearizer(): static	stabiel	3.2.0
Config	class	withLinearization(bool $linearize = true): self	stabiel	6.1.0
LinearizationView	class	fromPdf(string): self, lengthMatches(int): bool, publieke, alleen-lezen woordenboekvelden	stabiel	3.2.0

enableLinearization() gooit InvalidConfigException als er al versleuteling of een PAdES-handtekening is geconfigureerd. LinearizationView::fromPdf() retourneert een weergave waarin de vlag isLinearized false is voor een document zonder linearisatiewoordenboek.

Beperkingen

• Een gelineariseerd document kan niet tegelijk worden versleuteld of met PAdES worden ondertekend. Kies er per build één.
• De verouderde v1-backend genereert niet-conforme bijlage F-parameters en bestaat alleen voor bytecompatibiliteit met oudere uitvoer. De conformiteitscontrole wordt tegen v2 uitgevoerd.
• Fast Web View is een leveringsoptimalisatie, geen beveiligings- of validatiefunctie. Het wijzigt de weergegeven pagina-inhoud niet.