Mesin tata letak khusus dan intersepsi teks selama tata letak

Sekilas pandang

NextPDF tidak menyediakan antarmuka mesin tata letak yang dapat dipasang. Gunakan kontrak ekstensi tata letak publik, TextPreprocessorInterface, untuk mengintersepsi teks selama tata letak. Peristiwa siklus hidup konten memungkinkan Anda mengamati keluaran yang dihasilkan tata letak.

Instalasi

composer require nextpdf/core:^3

Ikhtisar konseptual

Alur tata letak bersifat internal. Alur ini mencakup tata letak glyph, subset font, keluaran ToUnicode CMap, dan pohon struktur. NextPDF tidak mengizinkan Anda menggantinya. Keluaran byte yang stabil dan kesesuaian tagged-PDF bergantung pada satu build yang terkendali.

NextPDF memang menyediakan titik sebelum tata letak: TextPreprocessorInterface. Implementasi menerima teks mentah dan mengembalikan hasil tersegmentasi sebelum teks tersebut memasuki tata letak glyph, subset font, ToUnicode CMap, atau pohon struktur. Gunakan jalur yang didukung ini untuk mengubah konten teks tanpa menyentuh mesin tata letak.

PHPDoc sumber menetapkan aturan tegas: implementasi tidak boleh mengubah cara kerja tata letak. Implementasi tidak boleh menambahkan karakter yang memengaruhi tata letak seperti line feed, carriage return, atau tab, dan harus mempertahankan urutan baca logis. Praprosesor menyatakan penggantian konten; praprosesor tidak membuat keputusan tata letak. Patuhi aturan ini, atau keluaran yang stabil dan aksesibilitas akan rusak.

Untuk mengamati hasil tata letak, bukan mengubahnya, gunakan peristiwa siklus hidup konten di Pemicu aksi dan pendengar peristiwa. ContentRenderedEvent dipicu setelah konten digambar ke halaman. FontLoadedEvent dipicu sekali untuk setiap keluarga dan gaya font.

Permukaan API

NextPDF\Contracts\TextPreprocessorInterface (stabil, sejak 1.9.0):

Metode	Mengembalikan	Tujuan
`process(string $text)`	`TextPreprocessResult`	Mengubah teks mentah sebelum alur rendering dan mengembalikan hasil tersegmentasi dengan metadata redaksi.

NextPDF\Contracts\TextPreprocessResult yang dikembalikan adalah objek nilai yang dibekukan. Tanda tangan konstruktor dan properti publiknya stabil dan tidak akan berubah dalam rilis minor atau patch. Metode baru dapat ditambahkan.

Contoh kode — Mulai cepat

Praprosesor sederhana di bawah ini menyamarkan token tertentu. Praprosesor ini tidak menambahkan karakter yang memengaruhi tata letak dan mempertahankan urutan baca.

<?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),
        ]);
    }
}

Contoh kode — Produksi

Praprosesor produksi menyimpan aturan pencocokan di satu tempat. Praprosesor ini gagal-tertutup saat pola bermasalah dan tidak pernah mencatat teks asli ke log.

<?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),
        ]);
    }
}

Kasus tepi & jebakan

Tidak ada penggantian tata letak. Anda tidak dapat mengganti tata letak kotak, pemenggalan baris, atau penomoran halaman melalui kontrak ini. Memasang mesin tata letak pihak ketiga sengaja berada di luar cakupan.
Penegakan aturan. Jika Anda menambahkan \n, \r, atau \t di dalam process(), Anda merusak tata letak dan menggagalkan keluaran yang stabil. Mesin memercayai aturan ini; ia tidak memeriksa ulang keluaran Anda untuk karakter yang memengaruhi tata letak.
Urutan baca. Jika Anda mengubah urutan segmen, Anda merusak urutan baca tagged-PDF dan kesesuaian PDF/UA.
Satu tanggung jawab. Praprosesor menyatakan penggantian konten. Gunakan peristiwa siklus hidup untuk mengamati, dan jangan memaksakan efek samping melalui process().

Kinerja

process() berjalan sekali untuk setiap text run pada jalur panas tata letak. Jaga penggunaan memori tetap rendah. Kompilasi pola sekali di dalam konstruktor, bukan pada setiap pemanggilan. Peristiwa siklus hidup konten tidak menimbulkan biaya saat tidak ada pendengar yang terikat.

Catatan keamanan

Gunakan TextPreprocessorInterface untuk menghapus konten sensitif sebelum konten itu mencapai aliran konten, subset font, atau metadata. Karena berjalan sebelum proses subset dan ToUnicode CMap, glyph yang diredaksi tidak pernah masuk ke dalam berkas. Perlakukan kegagalan praprosesor sebagai gagal-tertutup, dan keluarkan teks kosong atau teks yang disamarkan alih-alih teks asli.

Kesesuaian

Halaman ini tidak membuat klaim normatif tentang penandatanganan atau pengarsipan. Aturan urutan baca menyelaraskan kontrak dengan kebutuhan tagged-PDF. Referensi aksesibilitas mencakup kesesuaian pada tingkat tag.

Konteks komersial

NextPDF Pro menyediakan strategi prapemrosesan teks tingkat produksi, termasuk redaksi informasi pengenal pribadi (PII) yang telah disesuaikan untuk jenis dokumen umum. Di Core, Anda menulis TextPreprocessorInterface sendiri, atau menggunakan build edisi berbayar yang terverifikasi melalui kontrak publik yang sama.

Lihat juga

Kontrak dan modul terkait

Referensi kontrak tipografi — tempat TextPreprocessorInterface dan TextPreprocessResult dikatalogkan.
Referensi kontrak streaming — kontrak experimentalCursorInterface dan StreamingWriterInterface, dengan implementasi mesin yang telah dirilis.
Pemicu aksi dan pendengar peristiwa — peristiwa siklus hidup yang digunakan untuk mengamati keluaran tata letak.
Aturan stabilitas SPI — jaminan objek nilai yang dibekukan di balik TextPreprocessResult.
Ikhtisar penulisan ekstensi — permukaan lengkap antarmuka penyedia layanan (SPI) publik.

Glosarium mendefinisikan text preprocessor dan extension point; lihat glosarium yang diterbitkan untuk definisi kanonik masing-masing.