선형화: Fast Web View 출력

한눈에 보기

선형화된 PDF, 즉 Fast Web View는 파일의 나머지 부분이 도착하기 전에 리더가 첫 페이지를 표시할 수 있도록 배치됩니다. 첫 페이지의 객체, 해당 페이지의 상호 참조 하위 섹션, 다른 모든 페이지의 위치를 찾는 힌트 테이블이 모두 파일 앞부분에 배치됩니다. NextPDF는 이 레이아웃을 결정론적으로 생성합니다. 같은 문서는 어느 호스트에서나 같은 바이트를 생성하며, 그 출력은 qpdf --check-linearization을 통과합니다.

선형화는 Core 기능입니다. Document에서 옵트인하면 엔진이 3 패스 레이아웃, 선형화 매개변수 딕셔너리, 힌트 테이블을 처리합니다. 읽기 측의 LinearizationView는 완성된 파일의 선형화 딕셔너리를 파싱하므로, 전송 계층이 형식을 다시 구현하지 않고도 전달을 계획할 수 있습니다.

설치

composer require nextpdf/core:^3

개념 개요

표준 PDF는 상호 참조 테이블을 맨 끝에 배치하므로, 리더가 객체를 확인하려면 먼저 파일의 끝부분을 가져와야 합니다. 선형화된 PDF는 파일을 두 부분으로 재정렬합니다. 첫 번째 부분에는 선형화 매개변수 딕셔너리, 첫 페이지, 페이지 오프셋 힌트 테이블이 들어 있습니다. 두 번째 부분에는 나머지 페이지가 들어 있습니다. Fast Web View를 지원하는 리더는 첫 번째 부분에서 1 페이지를 렌더링한 다음, 바이트가 계속 도착하는 동안 힌트 테이블을 사용해 이후 어느 페이지로든 직접 이동할 수 있습니다 — ISO 32000-2 Annex F.

NextPDF는 두 가지 백엔드를 제공합니다. 기본 v2 백엔드는 적합한 페이지 오프셋 힌트 테이블과 정확한 파일 바이트 길이에 일치하는 /L 길이를 갖춘 ISO 32000-2 Annex F 출력을 생성하는 3 패스 선형화기입니다. 레거시 v1 백엔드는 v2 이전에 생성된 문서와의 바이트 호환성을 위해 유지됩니다. 이 백엔드는 적합하지 않은 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를 통해 옵트인할 수도 있습니다. 이 설정은 문서가 빌드될 때 적용되며, 문서마다 메서드를 호출하는 대신 전달 형식을 미리 고정하는 파이프라인에 적합합니다:

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

withLinearization()은 다른 Config 옵션과 마찬가지로 기본적으로 꺼져 있습니다. 이 선택을 명시적으로 나타내려면 false를 전달합니다. 이런 방식으로 빌드된 문서는 동일한 enableLinearization() 경로를 거치므로, 아래의 적합성 가드가 동일하게 적용됩니다.

적합성 상호작용

선형화는 태그가 지정된 프로파일 및 보관용 프로파일과 함께 사용할 수 있지만, 앞부분의 힌트 테이블이나 바이트 범위 서명을 무효화하는 기능과는 상호 배타적입니다.

기능	상호작용
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	class	enableLinearization(): static, useLegacyLinearizer(): static	안정	3.2.0
Config	class	withLinearization(bool $linearize = true): self	안정	6.1.0
LinearizationView	class	fromPdf(string): self, lengthMatches(int): bool, 공개 읽기 전용 딕셔너리 필드	안정	3.2.0

enableLinearization()은 암호화나 PAdES 서명이 이미 구성되어 있으면 InvalidConfigException을 발생시킵니다. LinearizationView::fromPdf()는 선형화 딕셔너리가 없는 문서의 경우 isLinearized 플래그가 false인 뷰를 반환합니다.

제한 사항

• 선형화된 문서는 동시에 암호화하거나 PAdES로 서명할 수 없습니다. 빌드마다 하나를 선택합니다.
• 레거시 v1 백엔드는 적합하지 않은 Annex F 매개변수를 생성하며, 이전 출력과의 바이트 호환성을 위해서만 존재합니다. 적합성 게이트는 v2를 대상으로 실행됩니다.
• Fast Web View는 전달 최적화이며, 보안이나 검증 기능이 아닙니다. 렌더링된 페이지 콘텐츠를 변경하지 않습니다.