Линеаризация: вывод для быстрого веб-просмотра (Fast Web View)

Кратко

Линеаризованный файл PDF (Portable Document Format), также известный как Fast Web View, устроен так, чтобы средство просмотра могло показать первую страницу ещё до получения всего файла. Объекты первой страницы, связанный с ней подраздел перекрёстных ссылок и таблица подсказок для всех остальных страниц находятся в начале файла. NextPDF формирует такую раскладку детерминированно: один и тот же документ на любом узле даёт одни и те же байты, а результат проходит проверку qpdf --check-linearization.

Линеаризация — функция Core. Чтобы использовать её, включите её для объекта Document; движок сам выполняет трёхпроходную раскладку, формирует словарь параметров линеаризации и таблицу подсказок. Представление на стороне чтения LinearizationView разбирает словарь линеаризации в готовом файле, поэтому транспортный уровень может планировать доставку, не реализуя формат заново.

Установка

composer require nextpdf/core:^3

Концептуальный обзор

В обычном PDF таблица перекрёстных ссылок находится в конце, поэтому средству просмотра приходится получить хвост файла, прежде чем оно сможет разрешить хотя бы один объект. В линеаризованном PDF файл организован в две части. Первая часть содержит словарь параметров линеаризации, первую страницу и таблицу подсказок смещений страниц. Вторая часть содержит остальные страницы. Средство просмотра с поддержкой Fast Web View может отрисовать первую страницу из первой части, а затем с помощью таблицы подсказок переходить напрямую к любой из последующих страниц по мере поступления байтов, как определено в приложении F (Annex F) стандарта ISO 32000-2.

NextPDF предоставляет два бэкенда. Бэкенд v2, используемый по умолчанию, — это трёхпроходный линеаризатор, который формирует вывод согласно приложению F (Annex F) стандарта ISO 32000-2 с соответствующей стандарту таблицей подсказок смещений страниц и значением /L, равным точной длине файла в байтах. Устаревший бэкенд v1 сохранён для байтовой совместимости с документами, созданными до v2; он формирует параметры, не соответствующие приложению F (Annex F), и доступен только при явном включении. Для новых задач используйте вариант по умолчанию.

Детерминированность гарантирована. Идентификатор файла вычисляется из дайджеста содержимого, а не из случайного источника, поэтому enableLinearization() является чистой функцией от документа. Это позволяет побайтовым эталонным тестам фиксировать вывод, а нижестоящим системам — использовать кэш с адресацией по содержимому или стабильный ETag.

Включение линеаризации

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

По умолчанию используется бэкенд v2. Чтобы выбрать устаревший бэкенд v1, вызовите useLegacyLinearizer() (порядок не важен):

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

Через конфигурацию

Линеаризацию также можно включить через Config. NextPDF применяет этот параметр при сборке документа; это подходит для конвейеров, где формат доставки выбирается заранее, а метод не вызывается для каждого документа:

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

Как и другие параметры Config, возможность withLinearization() по умолчанию отключена. Передайте false, чтобы сделать этот выбор явным. Документ, собранный таким образом, использует тот же путь выполнения, что и enableLinearization(), поэтому описанные ниже проверки соответствия применяются точно так же.

Взаимодействие с требованиями соответствия

Линеаризация совместима с теговым и архивным профилями, но взаимоисключаема с возможностями, из-за которых размещённая в начале таблица подсказок или подпись по диапазону байтов PDF Advanced Electronic Signatures (PAdES) стала бы недействительной.

Возможность	Взаимодействие
PDF/A, PDF/UA (профили)	Сочетаются. v2 сохраняет нумерацию объектов, поэтому ссылки на структуру и теги остаются действительными.
Шифрование (AES-256, AES-GCM, с открытым ключом)	Взаимоисключаемо. Поток подсказок был бы записан открытым текстом, поэтому движок отклоняет такое сочетание.
Подписи PAdES	Взаимоисключаемы. Повторная линеаризация перезаписала бы байтовые смещения и нарушила бы /ByteRange подписи.
Инкрементальные обновления	Взаимоисключаемы в рамках одной сборки.

Проверка двунаправленная и не зависит от порядка. Запрос шифрования (или подписи) для документа, уже отмеченного для линеаризации, вызывает исключение. Попытка пометить уже зашифрованный (или уже подписанный) документ для линеаризации также вызывает исключение. В обоих случаях возникает 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.
}

Чтение линеаризованного файла

LinearizationView разбирает словарь параметров линеаризации в начале готового PDF. Это единственная поддерживаемая точка входа для транспортного уровня, который планирует доставку; вызывающему коду не нужно заново реализовывать парсер словаря.

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

Тип	Вид	Ключевые члены	Стабильность	С версии
Document	класс	enableLinearization(): static, useLegacyLinearizer(): static	стабильно	3.2.0
Config	класс	withLinearization(bool $linearize = true): self	стабильно	6.1.0
LinearizationView	класс	fromPdf(string): self, lengthMatches(int): bool, открытые поля словаря, доступные только для чтения	стабильно	3.2.0

enableLinearization() вызывает InvalidConfigException, если уже настроены шифрование или подпись PAdES. LinearizationView::fromPdf() для документа без словаря линеаризации возвращает представление, у которого флаг isLinearized равен false.

Ограничения

• Линеаризованный документ нельзя одновременно шифровать или подписывать с помощью PAdES. Для каждой сборки выберите один вариант.
• Устаревший бэкенд v1 формирует параметры, не соответствующие приложению F (Annex F), и существует только для байтовой совместимости с более ранним выводом. Проверка соответствия выполняется относительно v2.
• Fast Web View — это оптимизация доставки, а не механизм безопасности или проверки. Она не меняет отображаемое содержимое страниц.