PageBackfill: bộ đệm trang retained

Tổng quan nhanh

Bản xem trước opt-in. Bộ đệm trang retained mặc định tắt. Khi nó tắt, bộ ghi vẫn là bộ serialize streaming như xưa nay — byte-identical. Chỉ bật nó khi bạn thực sự cần vẽ lên một trang trước đó, và hãy đọc danh sách fail-closed bên dưới trước đã.

Theo mặc định, bộ ghi stream các trang và flush chúng theo thứ tự; một khi một trang đã được flush thì không thể vẽ lên nó nữa. Bộ đệm trang retained là tùy chọn opt-in giữ các trang đã flush để một trang đã flush trước đó có thể được điền bù — vẽ lên một trang trước đó — trước khi tài liệu được serialize. Trường hợp kinh điển là một ô tổng hay một ô tóm tắt mà bạn chỉ có thể đặt sau khi các trang về sau đã được dàn xong.

Cài đặt

composer require nextpdf/core:^3

Bộ đệm trang retained đi kèm gói core. Config::withRetainedPageBuffer() và các phương thức điền bù của Document là @since 6.1.0. Mặc định vẫn là bộ ghi streaming. ADR-037, vốn trước đây đã hoãn năng lực này, nay được ghi nhận là đã triển khai.

Tổng quan khái niệm

Config::withRetainedPageBuffer() chọn một tài liệu vào các trang retained. Một khi bật, Document::setActiveBackfillPage(int $pageIndex) chuyển hướng vẽ sang một trang trước đó đã được flush; Document::endPageBackfill() đưa việc vẽ trở lại vị trí thêm bình thường. Nội dung bạn ghi giữa hai lệnh gọi này rơi vào trang trước đó. Bộ đệm giữ các trang cho tới save(), nên lần điền bù được áp dụng trước khi bảng tham chiếu chéo và trailer được ghi (ISO 32000-2 §7.5).

Ranh giới fail-closed — các tổ hợp bị từ chối

Điền bù là một thao tác truy cập ngẫu nhiên, và một số tính năng tài liệu giả định các byte chỉ-thêm, đã stream. Bộ đệm trang retained từ chối kết hợp với bất kỳ tính năng nào trong số đó, không phụ thuộc thứ tự và trước khi serialize, để nó không bao giờ âm thầm phá vỡ một chữ ký hay một tuyên bố tuân thủ:

• Một chữ ký số.
• PDF gắn thẻ (cây cấu trúc).
• PDF/A.
• Linearization.
• Đóng gói object-stream.
• Mã hóa.
• Chế độ kết xuất CSS Safe.

Một ngân sách byte-chưa-nén theo từng tài liệu chặn lượng mà bộ đệm có thể giữ; một tài liệu vượt quá nó sẽ hỏng cứng thay vì tiêu thụ bộ nhớ không giới hạn. Mặc định streaming vẫn fail closed ngay khoảnh khắc một bên gọi thử một lần chuyển truy-cập-ngẫu-nhiên mà không có tùy chọn opt-in — bật bộ đệm là cách duy nhất để có điền bù, và nó không tương thích với các tính năng trên theo thiết kế.

Bề mặt API

Ký hiệu	Vị trí	Vai trò
Config::withRetainedPageBuffer(bool $enabled = true): self	src/Core/Config.php	Chọn một tài liệu vào bộ đệm trang retained.
Document::setActiveBackfillPage(int $pageIndex): static	src/Core/Document.php	Chuyển hướng vẽ sang một trang trước đó đã được flush.
Document::endPageBackfill(): static	src/Core/Document.php	Đưa việc vẽ trở lại vị trí thêm bình thường.

Một lần điền bù vi phạm một tổ hợp bị từ chối sẽ làm phát sinh một ngoại lệ cấu hình có kiểu tại ranh giới, không phải một tài liệu hỏng.

Mẫu mã — Khởi đầu nhanh

Dành sẵn một chỗ trên trang một, điền phần còn lại của tài liệu, rồi điền bù chỗ đã dành bằng một giá trị tính ở cuối.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;

$config = (new Config())->withRetainedPageBuffer();

$doc = Document::createStandalone($config);
$doc->addPage();                 // page 0 — leaves room for a grand total
$doc->writeHtml('<h1>Invoice</h1>');

$doc->addPage();                 // page 1 — line items
$doc->writeHtml('<p>Line items…</p>');
$total = 1234.56;                // computed after laying out the items

$doc->setActiveBackfillPage(0);  // draw back onto page 0
$doc->writeHtml('<p>Grand total: ' . number_format($total, 2) . '</p>');
$doc->endPageBackfill();

$doc->save(__DIR__ . '/invoice.pdf');

Mẫu mã — Sản phẩm

Hãy tắt bộ đệm cho bất kỳ tài liệu nào đã ký, gắn thẻ, PDF/A, đã linearize, đã mã hóa, hoặc dùng object-stream — đó chính xác là các tổ hợp mà bộ đệm từ chối. Hãy chọn một đường một cách tường minh.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;

function renderReport(bool $needsBackfill, bool $mustBeSigned): Document
{
    if ($needsBackfill && $mustBeSigned) {
        // The buffer refuses to combine with signing. Resolve the requirement
        // before building: pre-compute the value, or sign a separate pass.
        throw new \LogicException('Back-fill and signing are mutually exclusive.');
    }

    $config = new Config();
    if ($needsBackfill) {
        $config = $config->withRetainedPageBuffer();
    }

    return Document::createStandalone($config);
}

Trường hợp đặc biệt & điểm cần lưu ý

• Tắt là byte-identical. Khi bộ đệm tắt, bộ ghi stream như trước.
• Loại trừ lẫn nhau với ký, gắn thẻ, PDF/A, linearization, object stream, mã hóa, và chế độ CSS Safe. Sự từ chối không phụ thuộc thứ tự và kích hoạt trước khi serialize. Hãy lập kế hoạch tài liệu cho chế độ này hoặc chế độ kia.
• Một ngân sách byte hỏng cứng. Bộ đệm retained có giới hạn; một tài liệu vượt quá ngân sách byte-chưa-nén sẽ hỏng thay vì lớn lên không giới hạn.
• Ghép cặp các lệnh gọi. Mỗi setActiveBackfillPage() nên được khớp bởi một endPageBackfill() để nội dung về sau được thêm bình thường.
• Mặc định streaming từ chối truy cập ngẫu nhiên. Không có tùy chọn opt-in, một lần chuyển truy-cập-ngẫu-nhiên sẽ fail closed. Bộ đệm là đường được hỗ trợ duy nhất.

Hiệu năng

Bộ đệm trang retained đánh đổi bộ nhớ lấy năng lực điền bù: nó giữ các trang đã flush cho tới save(), bị chặn bởi ngân sách byte-chưa-nén theo từng tài liệu. Hồ sơ bộ nhớ phẳng của bộ ghi streaming chỉ áp dụng khi bộ đệm tắt. performance_budget (wall_ms: 1500, peak_mb: 128) phản ánh trần bộ nhớ cao hơn của đường retained.

Ghi chú bảo mật

Bộ đệm trang retained không mở rộng bề mặt đầu vào; nó thay đổi thời điểm các byte được serialize, không phải cái gì được nạp vào. Việc nó từ chối kết hợp với mã hóa và ký là một thuộc tính an toàn: một lần điền bù không bao giờ có thể làm thay đổi các byte đã ký hay đã mã hóa sau khi đã xong, vì cả hai không thể được bật cùng nhau. Ngân sách byte chặn bộ nhớ trước một tài liệu thù địch.

Sự tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
Bộ ghi serialize phần thân, cấu trúc tham chiếu chéo, và trailer tại lúc save.	ISO 32000-2	§7.5

Đây là một năng lực xem trước. NextPDF từ chối bộ đệm điền bù cho các tài liệu đã ký, gắn thẻ, PDF/A, đã linearize, đã mã hóa, và object-stream, nên nó không đưa ra tuyên bố tuân thủ nào cho các hồ sơ đó qua đường này. Không có văn bản tiêu chuẩn nào được tái tạo.

Bộ chuyển đổi Compat (TCPDF)

Bộ chuyển đổi tương thích TCPDF phơi bày năng lực này dưới dạng một phần mở rộng hàm dựng. Hãy dựng bộ chuyển đổi với retainedPageBuffer: true, rồi một lệnh gọi setPage() hoặc lastPage() nhắm vào một trang trước đó sẽ ủy quyền cho điền bù của core thay vì làm phát sinh UnsupportedFeatureException của streaming. Đối số hàm dựng này là một phần mở rộng của NextPDF, không phải tương đương TCPDF cũ — TCPDF cũ không có cờ như vậy. Cùng các từ chối fail-closed áp dụng. Xem trang bộ đệm trang retained của bộ chuyển đổi compat để biết chi tiết phía bộ chuyển đổi.

Xem thêm

• Mô-đun Writer
• Mô-đun Document
• Mô-đun Config
• Mô-đun Linearization