Özel yerleşim motorları ve yerleşim sırasında metin yakalama

Bir bakışta

NextPDF takılabilir bir yerleşim motoru arabirimi sunmaz. Metni yerleşim sırasında yakalamak için genel yerleşim uzantısı sözleşmesini, yani TextPreprocessorInterface arabirimini kullanın. İçerik yaşam döngüsü olayları, yerleşimin ne ürettiğini gözlemlemenize olanak tanır.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Yerleşim ardışık düzeni dahilidir. Glif yerleşimini, yazı tipi alt kümelemeyi, ToUnicode CMap çıktısını ve yapı ağacını kapsar. NextPDF bunu değiştirmenize izin vermez. Kararlı bayt çıktısı ve etiketli PDF uyumluluğu, tek bir denetimli derlemeye bağlıdır.

NextPDF, bu noktayı aslında yerleşim öncesinde sunar: TextPreprocessorInterface. Bir uygulama, ham metni alır ve bu metin glif yerleşimine, yazı tipi alt kümelemesine, ToUnicode CMap’e veya yapı ağacına girmeden önce bölümlere ayrılmış bir sonuç döndürür. Yerleşim motoruna dokunmadan metin içeriğini değiştirmek için bu desteklenen yolu kullanın.

Kaynaktaki PHPDoc katı bir kural koyar: bir uygulama, yerleşimin çalışma biçimini değiştirmemelidir. Satır besleme, satır başı veya sekme gibi yerleşimi etkileyen karakterler eklememeli ve mantıksal okuma sırasını korumalıdır. Ön işlemci bir içerik değişimi bildirir; yerleşim seçimleri yapmaz. Bu kurala uyun; aksi hâlde kararlı çıktı ve erişilebilirlik bozulur.

Yerleşimin sonucunu değiştirmek için değil, gözlemlemek için Eylem tetikleyicileri ve olay dinleyicileri sayfasındaki içerik yaşam döngüsü olaylarını kullanın. ContentRenderedEvent, içerik bir sayfaya çizildikten sonra tetiklenir. FontLoadedEvent, her yazı tipi ailesi ve stili için bir kez tetiklenir.

API yüzeyi

NextPDF\Contracts\TextPreprocessorInterface (kararlı, 1.9.0 sürümünden beri):

Yöntem	Döndürür	Amaç
process(string $text)	TextPreprocessResult	Ham metni işleme ardışık düzeninden önce dönüştürür ve düzeltme üst verisini içeren, bölümlere ayrılmış bir sonuç döndürür.

Döndürülen NextPDF\Contracts\TextPreprocessResult dondurulmuş bir değer nesnesidir. Yapıcı imzası ve genel özellikleri kararlıdır ve bir alt veya yama sürümünde değişmez. Yeni yöntemler eklenebilir.

Kod örneği — hızlı başlangıç

Aşağıdaki küçük ön işlemci, sabit bir belirteci maskeler. Yerleşimi etkileyen herhangi bir karakter eklemez ve okuma sırasını korur.

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

Kod örneği — üretim

Üretim amaçlı bir ön işlemci, eşleştirme kurallarını tek bir yerde tutar. Hatalı bir desenle karşılaştığında güvenli şekilde kapanır ve özgün metni asla günlüğe kaydetmez.

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

Sınır durumları ve dikkat edilmesi gerekenler

• Yerleşimi değiştirme yok. Bu sözleşme aracılığıyla kutu yerleşimini, satır sonlandırmayı veya sayfalamayı değiştiremezsiniz. Üçüncü taraf bir yerleşim motorunun takılması, tasarım gereği kapsam dışıdır.
• Kuralın uygulanması. \n, \r veya \t karakterlerini process() içinde eklerseniz yerleşimi bozar ve kararlı çıktıyı zedelersiniz. Motor bu kurala güvenir; çıktınızı yerleşimi etkileyen karakterler için yeniden denetlemez.
• Okuma sırası. Bölümleri yeniden sıralarsanız etiketli PDF okuma sırasını ve PDF/UA uyumluluğunu bozarsınız.
• Tek bir sorumluluk. Ön işlemci bir içerik değişimi bildirir. İzlemek için yaşam döngüsü olaylarını kullanın ve yan etkileri process() üzerinden iletmeyin.

Performans

process(), yerleşimin sık çalışan yolunda her metin geçişi için bir kez çalışır. Bellek kullanımını düşük tutun. Desenleri her çağrıda değil, yapıcıda bir kez derleyin. Dinleyici bağlı olmadığında içerik yaşam döngüsü olayları hiçbir maliyete yol açmaz.

Güvenlik notları

Hassas içeriği kaldırmak için TextPreprocessorInterface arabirimini, içerik akışına, yazı tipi alt kümelerine veya üst veriye ulaşmadan önce kullanın. Alt kümelemeden ve ToUnicode CMap’ten önce çalıştığı için düzeltilmiş glifler dosyaya hiçbir zaman girmez. Bir ön işlemci hatasını güvenli kapanma durumu olarak ele alın ve özgün metin yerine boş veya maskelenmiş metin verin.

Uyumluluk

Bu sayfa, normatif imzalama veya arşivleme iddialarında bulunmaz. Okuma sırası kuralı, sözleşmeyi etiketli PDF gereksinimleriyle hizalar. Erişilebilirlik başvuru kaynağı, etiket düzeyindeki uyumluluğu kapsar.

Ticari bağlam

NextPDF Pro, kişisel olarak tanımlanabilir bilgilerin (PII) düzeltilmesi dahil, yaygın belge türleri için ayarlanmış üretime hazır metin ön işleme stratejileri sağlar. Core’da TextPreprocessorInterface arabirimini ya kendiniz yazarsınız ya da aynı genel sözleşme üzerinden doğrulanmış bir ücretli sürüm derlemesini kullanırsınız.

Ayrıca bkz.

• Uzantı yazımına genel bakış
• Eylem tetikleyicileri ve olay dinleyicileri
• Özel yazı tipleri
• SPI kararlılık kuralları

İlgili sözleşmeler ve modüller

• Tipografi sözleşmeleri başvurusu — TextPreprocessorInterface ve TextPreprocessResult sözleşmelerinin kataloglandığı yer.
• Akış sözleşmeleri başvurusu — yayımlanmış bir motor uygulaması bulunan experimentalCursorInterface ve StreamingWriterInterface sözleşmeleri.
• Eylem tetikleyicileri ve olay dinleyicileri — yerleşim çıktısını gözlemlemek için kullanılan yaşam döngüsü olayları.
• SPI kararlılık kuralları — TextPreprocessResult ardındaki dondurulmuş değer nesnesi taahhüdü.
• Uzantı yazımına genel bakış — genel hizmet sağlayıcı arabirimi (SPI) yüzeyinin tamamı.

Sözlük, metin ön işlemcisi ve uzantı noktası terimlerini tanımlar; her bir kurallı tanım için yayımlanan sözlüğe bakın.