Công cụ bố cục tùy chỉnh và can thiệp văn bản tại thời điểm bố cục

Tổng quan nhanh

NextPDF không cung cấp giao diện công cụ bố cục dạng plugin. Hãy dùng hợp đồng mở rộng bố cục công khai, TextPreprocessorInterface, để can thiệp vào văn bản tại thời điểm bố cục. Các sự kiện vòng đời nội dung cho phép bạn quan sát nội dung do bố cục tạo ra.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Quy trình bố cục là nội bộ. Quy trình này bao gồm bố cục glyph, tạo tập con phông chữ, xuất ToUnicode CMap và cây cấu trúc. NextPDF không cho phép bạn thay thế quy trình đó. Đầu ra ổn định ở cấp byte và việc tuân thủ tagged-PDF phụ thuộc vào một bản dựng được kiểm soát.

NextPDF có cung cấp một điểm trước bố cục: TextPreprocessorInterface. Một triển khai nhận văn bản thô và trả về một kết quả đã phân đoạn trước khi văn bản đó được đưa vào bố cục glyph, tạo tập con phông chữ, ToUnicode CMap hoặc cây cấu trúc. Hãy dùng cách được hỗ trợ này để thay đổi nội dung văn bản mà không chạm vào công cụ bố cục.

PHPDoc nguồn đặt ra một quy tắc nghiêm ngặt: một triển khai không được thay đổi cách bố cục hoạt động. Nó không được thêm các ký tự ảnh hưởng đến bố cục như xuống dòng, về đầu dòng hoặc tab, và phải giữ nguyên thứ tự đọc logic. Bộ tiền xử lý chỉ khai báo một thay thế nội dung; nó không đưa ra các lựa chọn bố cục. Hãy tuân thủ quy tắc này; nếu không, đầu ra ổn định và khả năng truy cập sẽ bị phá vỡ.

Để quan sát kết quả của bố cục mà không thay đổi nó, hãy dùng các sự kiện vòng đời nội dung trong Trình kích hoạt hành động và trình lắng nghe sự kiện. ContentRenderedEvent kích hoạt sau khi nội dung được vẽ lên một trang. FontLoadedEvent kích hoạt một lần cho mỗi họ phông chữ và kiểu chữ.

Bề mặt API

NextPDF\Contracts\TextPreprocessorInterface (ổn định, kể từ 1.9.0):

Phương thức	Trả về	Mục đích
`process(string $text)`	`TextPreprocessResult`	Biến đổi văn bản thô trước quy trình kết xuất và trả về một kết quả đã phân đoạn kèm siêu dữ liệu lược bỏ.

Kết quả NextPDF\Contracts\TextPreprocessResult được trả về là một đối tượng giá trị đông cứng. Chữ ký hàm khởi tạo và các thuộc tính công khai của nó ổn định và sẽ không thay đổi trong một bản phát hành minor hoặc patch. Các phương thức mới có thể được bổ sung.

Mẫu mã — bắt đầu nhanh

Bộ tiền xử lý nhỏ dưới đây che một token cố định. Nó không thêm bất kỳ ký tự nào ảnh hưởng đến bố cục và vẫn giữ nguyên thứ tự đọc.

<?php

declare(strict_types=1);

use NextPDF\Contracts\TextPreprocessorInterface;
use NextPDF\Contracts\TextPreprocessResult;
use NextPDF\Contracts\TextSegment;

final class TokenMaskingPreprocessor implements TextPreprocessorInterface
{
    public function process(string $text): TextPreprocessResult
    {
        $masked = \str_replace('SECRET-TOKEN', '••••••••••••', $text);

        return new TextPreprocessResult([
            new TextSegment($masked, redacted: $masked !== $text),
        ]);
    }
}

Mẫu mã — môi trường sản xuất

Một bộ tiền xử lý cho môi trường sản xuất tập trung các quy tắc khớp mẫu vào một nơi. Nó thất bại theo hướng đóng khi gặp mẫu bị lỗi và không bao giờ ghi nhật ký văn bản gốc.

<?php

declare(strict_types=1);

use NextPDF\Contracts\TextPreprocessorInterface;
use NextPDF\Contracts\TextPreprocessResult;
use NextPDF\Contracts\TextSegment;
use Psr\Log\LoggerInterface;

final class PatternRedactionPreprocessor implements TextPreprocessorInterface
{
    /**
     * @param non-empty-string $pattern A valid PCRE pattern for sensitive spans
     */
    public function __construct(
        private readonly string $pattern,
        private readonly LoggerInterface $logger,
    ) {}

    public function process(string $text): TextPreprocessResult
    {
        $result = \preg_replace($this->pattern, '[REDACTED]', $text);

        if ($result === null) {
            // Fail closed: never emit unredacted text on a pattern error.
            $this->logger->error('Redaction pattern failed; substituting empty text');

            return new TextPreprocessResult([new TextSegment('', redacted: true)]);
        }

        return new TextPreprocessResult([
            new TextSegment($result, redacted: $result !== $text),
        ]);
    }
}

Trường hợp biên & lưu ý

Không thay thế bố cục. Bạn không thể thay thế bố cục hộp, ngắt dòng hoặc phân trang thông qua hợp đồng này. Việc tích hợp một công cụ bố cục của bên thứ ba nằm ngoài phạm vi theo thiết kế.
Thực thi quy tắc. Nếu bạn thêm \n, \r, hoặc \t vào process(), bạn làm hỏng bố cục và phá vỡ đầu ra ổn định. Công cụ dựa vào quy tắc này; nó không kiểm tra lại đầu ra của bạn để phát hiện các ký tự ảnh hưởng đến bố cục.
Thứ tự đọc. Nếu bạn sắp xếp lại các phân đoạn, bạn phá vỡ thứ tự đọc của tagged-PDF và việc tuân thủ PDF/UA.
Một trách nhiệm. Bộ tiền xử lý chỉ khai báo một thay thế nội dung. Hãy dùng các sự kiện vòng đời để theo dõi, và đừng đưa tác dụng phụ vào process().

Hiệu năng

process() chạy một lần cho mỗi lần chạy văn bản trên đường dẫn nóng của bố cục. Hãy giữ mức sử dụng bộ nhớ thấp. Hãy biên dịch các mẫu một lần trong hàm khởi tạo, không phải trên mỗi lần gọi. Các sự kiện vòng đời nội dung không phát sinh chi phí khi không có trình lắng nghe nào được gắn.

Lưu ý bảo mật

Hãy dùng TextPreprocessorInterface để loại bỏ nội dung nhạy cảm trước khi nội dung đó đến luồng nội dung, các tập con phông chữ hoặc siêu dữ liệu. Vì nó chạy trước khi tạo tập con và ToUnicode CMap, các glyph đã lược bỏ không bao giờ đi vào tệp. Hãy coi lỗi của bộ tiền xử lý là một thất bại theo hướng đóng và phát ra văn bản trống hoặc đã che thay vì văn bản gốc.

Tuân thủ

Trang này không đưa ra tuyên bố quy chuẩn nào về ký hay lưu trữ. Quy tắc thứ tự đọc giúp hợp đồng phù hợp với các nhu cầu của tagged-PDF. Tài liệu tham khảo về khả năng truy cập bao gồm việc tuân thủ ở cấp thẻ.

Bối cảnh thương mại

NextPDF Pro cung cấp các chiến lược tiền xử lý văn bản cho môi trường sản xuất, bao gồm lược bỏ thông tin định danh cá nhân (PII) được tinh chỉnh cho các loại tài liệu phổ biến. Trong Core, bạn tự viết TextPreprocessorInterface, hoặc dùng một bản dựng phiên bản trả phí đã được xác minh thông qua cùng hợp đồng công khai đó.

Xem thêm

Các hợp đồng và mô-đun liên quan

Tài liệu tham khảo về hợp đồng kiểu chữ — nơi TextPreprocessorInterface và TextPreprocessResult được liệt kê.
Tài liệu tham khảo về hợp đồng phát luồng — các hợp đồng experimentalCursorInterface và StreamingWriterInterface, vốn đã có một triển khai công cụ được phát hành.
Trình kích hoạt hành động và trình lắng nghe sự kiện — các sự kiện vòng đời được dùng để quan sát đầu ra của bố cục.
Quy tắc ổn định SPI — lời hứa về đối tượng giá trị đông cứng đứng sau TextPreprocessResult.
Tổng quan về soạn phần mở rộng — toàn bộ bề mặt giao diện nhà cung cấp dịch vụ (SPI) công khai.

Bảng thuật ngữ định nghĩa bộ tiền xử lý văn bản và điểm mở rộng; hãy xem bảng thuật ngữ đã xuất bản để biết từng định nghĩa chuẩn tắc.