Tuyến tính hóa: đầu ra Fast Web View

Tổng quan nhanh

Một tệp Portable Document Format (PDF) được tuyến tính hóa, còn gọi là Fast Web View, được sắp xếp để trình đọc có thể hiển thị trang đầu tiên trước khi toàn bộ tệp được tải xong. Các đối tượng của trang đầu tiên, phần con tham chiếu chéo của trang đó, và bảng gợi ý cho mọi trang còn lại đều nằm gần đầu tệp. NextPDF xuất bố cục này theo cách tất định: cùng một tài liệu sẽ tạo ra cùng các byte trên mọi máy, và kết quả vượt qua qpdf --check-linearization.

Tuyến tính hóa là một tính năng của Core. Để dùng tính năng này, hãy bật trên Document; engine sẽ xử lý bố cục ba lượt, từ điển tham số tuyến tính hóa, và bảng gợi ý. LinearizationView ở phía đọc phân tích từ điển tuyến tính hóa trong một tệp đã hoàn thiện, nhờ đó lớp truyền tải có thể lập kế hoạch phân phối mà không cần triển khai lại định dạng.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Một tệp PDF tiêu chuẩn đặt bảng tham chiếu chéo ở cuối, nên trình đọc phải lấy phần đuôi tệp trước khi có thể phân giải bất kỳ đối tượng nào. Một tệp PDF được tuyến tính hóa tổ chức tệp thành hai phần. Phần thứ nhất chứa từ điển tham số tuyến tính hóa, trang đầu tiên, và bảng gợi ý độ lệch trang. Phần thứ hai chứa các trang còn lại. Một trình đọc hỗ trợ Fast Web View có thể kết xuất trang đầu tiên từ phần thứ nhất, rồi dùng bảng gợi ý để nhảy trực tiếp đến bất kỳ trang nào về sau khi các byte tiếp tục được tải về, đúng như định nghĩa trong ISO 32000-2 Annex F.

NextPDF cung cấp hai backend. Backend v2 mặc định là bộ tuyến tính hóa ba lượt, tạo ra đầu ra ISO 32000-2 Annex F với bảng gợi ý độ lệch trang tuân thủ chuẩn và độ dài /L bằng đúng độ dài byte chính xác của tệp. Backend v1 kế thừa vẫn còn để tương thích byte với các tài liệu được tạo trước v2; nó xuất các tham số Annex F không tuân thủ chuẩn và chỉ dùng khi được bật tường minh. Với công việc mới, hãy dùng mặc định.

Tính tất định được bảo đảm. Định danh tệp đến từ digest nội dung, không phải từ nguồn ngẫu nhiên, nên enableLinearization() là một hàm thuần của tài liệu. Điều này cho phép các bài kiểm thử golden byte ghim chặt đầu ra và cho phép các hệ thống phía sau dùng cache định địa chỉ theo nội dung hoặc một ETag ổn định.

Bật tuyến tính hóa

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

Backend mặc định là v2. Để dùng backend v1 kế thừa, hãy gọi useLegacyLinearizer() trước (thứ tự nào cũng được):

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

Từ cấu hình

Bạn cũng có thể bật thông qua Config. NextPDF áp dụng thiết lập này khi dựng tài liệu, phù hợp với các pipeline chọn định dạng phân phối ngay từ đầu thay vì gọi một phương thức trên từng tài liệu:

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

Giống các tùy chọn Config khác, withLinearization() mặc định là tắt. Hãy truyền false để lựa chọn đó trở nên tường minh. Một tài liệu được dựng theo cách này dùng cùng đường dẫn enableLinearization(), nên các bộ bảo vệ tuân thủ bên dưới áp dụng y hệt.

Tương tác về tuân thủ

Tuyến tính hóa hoạt động cùng các hồ sơ được gắn thẻ và hồ sơ lưu trữ, nhưng loại trừ lẫn nhau với các tính năng làm mất hiệu lực bảng gợi ý đặt phía trước hoặc một chữ ký theo dải byte PDF Advanced Electronic Signatures (PAdES).

Tính năng	Tương tác
PDF/A, PDF/UA	Kết hợp được. v2 giữ nguyên cách đánh số đối tượng, nên cấu trúc và các tham chiếu thẻ vẫn hợp lệ.
Mã hóa (AES-256, AES-GCM, khóa công khai)	Loại trừ lẫn nhau. Luồng gợi ý sẽ bị xuất dưới dạng văn bản thuần, nên engine từ chối cặp này.
Chữ ký PAdES	Loại trừ lẫn nhau. Tuyến tính hóa lại ghi lại các độ lệch byte và sẽ làm hỏng /ByteRange của chữ ký.
Cập nhật tăng dần	Loại trừ lẫn nhau trên cùng một lần dựng.

Bộ bảo vệ này có tính hai chiều và không phụ thuộc vào thứ tự. Yêu cầu mã hóa (hoặc một chữ ký) trên một tài liệu đã được đánh dấu tuyến tính hóa sẽ ném lỗi. Đánh dấu tuyến tính hóa cho một tài liệu đã được mã hóa (hoặc đã được ký) cũng ném lỗi. Cả hai đường dẫn đều ném 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.
}

Đọc một tệp đã tuyến tính hóa

LinearizationView phân tích từ điển tham số tuyến tính hóa ở phần đầu của một tệp PDF đã hoàn thiện. Đây là điểm truy cập duy nhất được hỗ trợ cho lớp truyền tải lập kế hoạch phân phối; bên gọi không bao giờ phải triển khai lại bộ phân tích từ điển.

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

Bề mặt API

Kiểu	Loại	Thành viên chính	Độ ổn định	Từ phiên bản
Document	class	enableLinearization(): static, useLegacyLinearizer(): static	ổn định	3.2.0
Config	class	withLinearization(bool $linearize = true): self	ổn định	6.1.0
LinearizationView	class	fromPdf(string): self, lengthMatches(int): bool, các trường từ điển công khai chỉ đọc	ổn định	3.2.0

enableLinearization() ném InvalidConfigException khi mã hóa hoặc một chữ ký PAdES đã được cấu hình. LinearizationView::fromPdf() trả về một khung nhìn có cờ isLinearized bằng false đối với một tài liệu không có từ điển tuyến tính hóa.

Giới hạn

• Một tài liệu đã tuyến tính hóa không thể đồng thời được mã hóa hoặc được ký bằng PAdES. Hãy chọn một thứ cho mỗi lần dựng.
• Backend v1 kế thừa xuất các tham số Annex F không tuân thủ chuẩn và chỉ tồn tại để tương thích byte với đầu ra cũ. Cổng kiểm tra tuân thủ chạy với v2.
• Fast Web View là một tối ưu hóa phân phối, không phải một tính năng bảo mật hay kiểm định. Nó không thay đổi nội dung trang đã kết xuất.