Linearization: saída Fast Web View

Visão geral

Um arquivo Portable Document Format (PDF) linearizado, também chamado de Fast Web View, é organizado para que um leitor consiga exibir a primeira página antes de receber o arquivo completo. Os objetos da primeira página, sua subseção de cross-reference e a hint table de todas as outras páginas ficam próximos ao início do arquivo. O NextPDF emite esse layout de forma determinística: o mesmo documento produz os mesmos bytes em todos os hosts, e o resultado passa em qpdf --check-linearization.

A linearization é um recurso do Core. Para usá-la, ative-a no Document; o engine cuida do layout em três passagens, do linearization parameter dictionary e da hint table. A LinearizationView do lado de leitura analisa o linearization dictionary em um arquivo finalizado, para que um transporte possa planejar a entrega sem reimplementar o formato.

Instalação

composer require nextpdf/core:^3

Visão conceitual

Um PDF padrão coloca sua cross-reference table no final, de modo que um leitor precisa buscar o fim do arquivo antes de conseguir resolver qualquer objeto. Um PDF linearizado organiza o arquivo em duas partes. A primeira parte contém o linearization parameter dictionary, a primeira página e a page-offset hint table. A segunda parte contém as páginas restantes. Um leitor com suporte a Fast Web View pode renderizar a primeira página a partir da primeira parte e, em seguida, usar a hint table para ir diretamente a qualquer página posterior à medida que os bytes continuam chegando, conforme definido pelo Annex F da ISO 32000-2.

O NextPDF oferece dois backends. O backend padrão v2 é um linearizer de três passagens que produz a saída do Annex F da ISO 32000-2 com uma page-offset hint table em conformidade e um comprimento /L igual ao comprimento exato em bytes do arquivo. Um backend legado v1 permanece disponível para compatibilidade de bytes com documentos produzidos antes do v2; ele emite parâmetros do Annex F fora de conformidade e funciona apenas com ativação explícita. Para trabalhos novos, use o padrão.

O determinismo é garantido. O identificador do arquivo vem do digest do conteúdo, não de uma fonte aleatória, de modo que enableLinearization() é uma função pura do documento. Isso permite que golden byte tests fixem a saída e que sistemas downstream usem um cache endereçado por conteúdo ou um ETag estável.

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

O backend padrão é o v2. Para usar o backend legado v1, chame useLegacyLinearizer() primeiro (qualquer ordem funciona):

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

A partir da configuração

Você também pode ativar esse recurso por meio de Config. O NextPDF aplica a configuração ao construir o documento, o que se adapta a pipelines que escolhem o formato de entrega antecipadamente em vez de chamar um método em cada documento:

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

Assim como outras opções de Config, withLinearization() vem desativado por padrão. Passe false para tornar essa escolha explícita. Um documento construído dessa forma usa o mesmo caminho de enableLinearization(), portanto as conformance guards abaixo se aplicam de forma idêntica.

Interações de conformidade

A linearization funciona com os perfis tagged e archival, mas é mutuamente exclusiva com recursos que invalidariam a hint table inicial ou uma assinatura por byte-range de PDF Advanced Electronic Signatures (PAdES).

Recurso	Interação
PDF/A, PDF/UA	São compatíveis. O v2 preserva a numeração dos objetos, de modo que as referências de estrutura e tags permanecem válidas.
Criptografia (AES-256, AES-GCM, chave pública)	Mutuamente exclusivos. O hint stream seria emitido em texto puro, por isso o engine rejeita o par.
Assinaturas PAdES	Mutuamente exclusivos. A relinearization reescreve os offsets de bytes e quebraria o /ByteRange de uma assinatura.
Atualizações incrementais	Mutuamente exclusivos em um único build.

A guarda é bidirecional e independe da ordem. Solicitar criptografia (ou uma assinatura) em um documento já marcado para linearization lança uma exceção. Marcar para linearization um documento já criptografado (ou já assinado) também lança uma exceção. Ambos os caminhos lançam 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.
}

Lendo um arquivo linearizado

LinearizationView analisa o linearization parameter dictionary no início de um PDF finalizado. Esse é o único ponto de entrada suportado para um transporte que planeja a entrega; quem chama nunca reimplementa o parser do dictionary.

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

Superfície da API

Tipo	Categoria	Membros principais	Estabilidade	Desde
Document	classe	enableLinearization(): static, useLegacyLinearizer(): static	estável	3.2.0
Config	classe	withLinearization(bool $linearize = true): self	estável	6.1.0
LinearizationView	classe	fromPdf(string): self, lengthMatches(int): bool, campos públicos somente leitura do dictionary	estável	3.2.0

enableLinearization() lança InvalidConfigException quando a criptografia ou uma assinatura PAdES já está configurada. LinearizationView::fromPdf() retorna uma view em que o flag isLinearized é false para um documento sem linearization dictionary.

Limitações

• Um documento linearizado não pode também ser criptografado nem assinado com PAdES. Escolha um por build.
• O backend legado v1 emite parâmetros do Annex F fora de conformidade e existe apenas para compatibilidade de bytes com saídas mais antigas. A conformance gate é executada contra o v2.
• Fast Web View é uma otimização de entrega, não um recurso de segurança ou validação. Ela não altera o conteúdo renderizado da página.