Niestandardowe silniki układu i przechwytywanie tekstu podczas układania

W skrócie

NextPDF nie udostępnia wtykowego interfejsu silnika układu. Użyj publicznego kontraktu rozszerzania układu, TextPreprocessorInterface, aby wpiąć się w tekst podczas układania. Zdarzenia cyklu życia treści pozwalają obserwować wynik pracy układu.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Potok układu jest wewnętrzny. Obejmuje układanie glifów, tworzenie podzbiorów czcionek, generowanie mapy ToUnicode CMap oraz drzewo struktury. NextPDF nie pozwala go zastąpić. Stabilność wyjścia na poziomie bajtów i zgodność z PDF ze znacznikami zależą od jednej kontrolowanej kompilacji.

NextPDF udostępnia natomiast punkt przed układaniem: TextPreprocessorInterface. Implementacja otrzymuje surowy tekst i zwraca podzielony na segmenty wynik, zanim tekst trafi do układania glifów, tworzenia podzbiorów czcionek, mapy ToUnicode CMap lub drzewa struktury. Użyj tej obsługiwanej ścieżki, aby zmieniać treść tekstu bez ingerowania w silnik układu.

PHPDoc w źródłach ustanawia twardą regułę: implementacja nie może zmieniać sposobu działania układu. Nie może dodawać znaków wpływających na układ, takich jak znak nowego wiersza, powrót karetki czy tabulacja, i musi zachowywać logiczną kolejność czytania. Preprocesor deklaruje podmianę treści; nie podejmuje decyzji dotyczących układu. Przestrzegaj tej reguły, inaczej stabilność wyjścia i dostępność przestaną być zachowane.

Aby obserwować wynik układania, a nie go zmieniać, użyj zdarzeń cyklu życia treści opisanych w Wyzwalacze akcji i nasłuchiwacze zdarzeń. Zdarzenie ContentRenderedEvent jest wyzwalane po narysowaniu treści na stronie. Zdarzenie FontLoadedEvent jest wyzwalane raz dla każdej rodziny i każdego stylu czcionki.

Powierzchnia API

NextPDF\Contracts\TextPreprocessorInterface (stabilny, od 1.9.0):

Metoda	Zwraca	Przeznaczenie
process(string $text)	TextPreprocessResult	Przekształca surowy tekst przed potokiem renderowania i zwraca podzielony na segmenty wynik wraz z metadanymi redakcji.

Zwrócony obiekt NextPDF\Contracts\TextPreprocessResult to zamrożony obiekt wartości. Sygnatura konstruktora i właściwości publiczne są stabilne i nie zmieniają się w wydaniu pomniejszym ani poprawkowym. Mogą zostać dodane nowe metody.

Przykład kodu — szybki start

Prosty preprocesor poniżej maskuje stały token. Nie dodaje żadnych znaków wpływających na układ i zachowuje kolejność czytania.

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

Przykład kodu — wersja produkcyjna

Produkcyjny preprocesor utrzymuje reguły dopasowania w jednym miejscu. W razie błędnego wzorca działa w trybie fail-closed i nigdy nie zapisuje w dzienniku oryginalnego tekstu.

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

Przypadki brzegowe i pułapki

• Brak podmiany układu. Za pomocą tego kontraktu nie można zastąpić układu blokowego, łamania wierszy ani podziału na strony. Podłączenie zewnętrznego silnika układu jest celowo poza zakresem.
• Przestrzeganie reguły. Jeśli dodasz \n, \r lub \t w process(), uszkodzisz układ i zepsujesz stabilne wyjście. Silnik zakłada spełnienie tej reguły; nie waliduje ponownie wyjścia pod kątem znaków wpływających na układ.
• Kolejność czytania. Jeśli zmienisz kolejność segmentów, naruszysz kolejność czytania w PDF ze znacznikami oraz zgodność z PDF/UA.
• Jedna odpowiedzialność. Preprocesor deklaruje podmianę treści. Do obserwowania używaj zdarzeń cyklu życia i nie przenoś efektów ubocznych przez process().

Wydajność

process() wykonuje się raz dla każdego przebiegu tekstu na krytycznej ścieżce układania. Utrzymuj niskie zużycie pamięci. Kompiluj wzorce raz w konstruktorze, a nie przy każdym wywołaniu. Zdarzenia cyklu życia treści nie generują kosztu, gdy nie podpięto żadnego nasłuchiwacza.

Uwagi dotyczące bezpieczeństwa

Użyj TextPreprocessorInterface, aby usunąć poufne treści, zanim trafią do strumienia treści, podzbiorów czcionek lub metadanych. Ponieważ preprocesor działa przed tworzeniem podzbiorów i mapy ToUnicode CMap, zredagowane glify nigdy nie trafiają do pliku. Traktuj awarię preprocesora jako fail-closed i zwracaj pusty lub zamaskowany tekst zamiast oryginału.

Zgodność

Ta strona nie formułuje normatywnych twierdzeń dotyczących podpisywania ani archiwizacji. Reguła kolejności czytania dostosowuje kontrakt do potrzeb PDF ze znacznikami. Dokumentacja dostępności omawia zgodność na poziomie znaczników.

Kontekst komercyjny

NextPDF Pro dostarcza produkcyjne strategie wstępnego przetwarzania tekstu, w tym redakcję informacji umożliwiających identyfikację osoby (PII) dostrojoną do typowych typów dokumentów. W edycji Core implementujesz TextPreprocessorInterface samodzielnie albo korzystasz ze zweryfikowanej kompilacji edycji płatnej za pośrednictwem tego samego publicznego kontraktu.

Zobacz też

• Przegląd tworzenia rozszerzeń
• Wyzwalacze akcji i nasłuchiwacze zdarzeń
• Niestandardowe czcionki
• Reguły stabilności SPI

Powiązane kontrakty i moduły

• Dokumentacja kontraktów typografii — gdzie skatalogowano TextPreprocessorInterface oraz TextPreprocessResult.
• Dokumentacja kontraktów strumieniowania — kontrakty experimentalCursorInterface oraz StreamingWriterInterface, dla których dostarczono implementację silnika.
• Wyzwalacze akcji i nasłuchiwacze zdarzeń — zdarzenia cyklu życia używane do obserwowania wyjścia układu.
• Reguły stabilności SPI — gwarancja zamrożonego obiektu wartości stojąca za TextPreprocessResult.
• Przegląd tworzenia rozszerzeń — pełna powierzchnia publicznego interfejsu dostawcy usług (SPI).

Słownik zawiera definicje pojęć preprocesor tekstu oraz punkt rozszerzenia; kanoniczne brzmienie każdej z nich znajdziesz w opublikowanym słowniku.