Sözleşmeler / tipografi

Genel bakış

Tipografi alanı, yazı tipi kayıt defteri ve metin ön işleme sözleşmelerini tanımlar: FontRegistryInterface, TextPreprocessorInterface ile değiştirilemez TextPreprocessResult ve TextSegment değer nesneleri. Tümü stable kararlılık düzeyindedir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

FontRegistryInterface, süreç ömrü boyunca geçerli kalan yazı tipi deposudur. Bir TrueType, OpenType, TrueType Collection (TTC) veya Printer Font Binary (PFB) yazı tipini kaydeder ve ayrıştırılmış FontInfo meta verilerini döndürür. Kayıt defteri tek tek belgelerden daha uzun ömürlü olduğu için, bir çalışan her yazı tipini yalnızca bir kez ayrıştırır. Önyükleme sırasında bir yazı tipi grubunu ısıtabilir, ardından kayıt defterini kilitleyerek üretim trafiğinin onu değiştirmesini önleyebilirsiniz. Kilitli bir kayıt defteri şu yöntemlerde LogicException fırlatır: register(), addFontDirectory() veya warmup(); arama işlemleri kullanılabilir kalır. Kayıt defteri, registerFromBinary() aracılığıyla ham yazı tipi baytlarını da kabul eder. @font-face köprüsü, uzak bir kaynaktan veya bir veri URI’sinden (uniform resource identifier) getirilen bir yazı tipini kaydetmek için bu yöntemi kullanır. Kayıt defteri yalnızca saf PHP verilerini saklar; kaynak tanıtıcısı içermez, bu nedenle bir çalışan havuzu boyunca paylaşılabilir.

Motor, kullandığı her yazı tipini gömer ve alt kümeye ayırır. Gömülü bir yazı tipi programı Portable Document Format (PDF) dosyasının içinde yer alır; böylece belge, yüklü sistem yazı tiplerinden bağımsız olarak her görüntüleyicide aynı şekilde işlenir — ISO 32000-2 §9. Bir yazı tipi alt kümesi yalnızca belgenin gerçekten başvurduğu glifleri içerir. Bu durum en çok Çince, Japonca ve Korece (CJK) veya Unicode bakımından zengin diğer içerikler için önemlidir — ISO 32000-2 §9. Kayıt defteri sözleşmesi, alt kümeleme ve gömme aşamalarının kullandığı ayrıştırılmış meta verileri sunar.

TextPreprocessorInterface, metin glif yerleşimine, yazı tipi alt kümelemesine, ToUnicode karakter eşlemesine (CMap) ve yapı ağacına girmeden önce metne müdahale eder. Bu konumlandırma bir güvenlik özelliğidir: içeriği gizleyen bir ön işlemci, gizlenecek içeriği içerik akışına, yazı tipi alt kümesine veya meta verilere ulaşmadan önce kaldırır. Sözleşme iki değişmez kural içerir. Bir ön işlemci yerleşimi etkileyen karakterler eklememeli ve mantıksal okuma sırasını korumalıdır; sorumluluğu yerleşim değil, içerik değişikliğidir. Sonuç, değiştirilemez bir TextPreprocessResult nesnesidir ve sıralı bir TextSegment değerleri listesi içerir. Bir segment ya geçişlidir ya da gizlenmiştir. Gizlenmiş bir segment için görüntülenen metin maskeleme moduna bağlıdır: kara kutu dikdörtgeni için boş, özgün uzunlukla eşleşen yıldız işaretleri veya sabit bir etiket. Bir segmentteki originalCharCount, yalnızca bir gizleme dikdörtgeninin boyutunu belirlemek için kullanılan, geri döndürülemez bir ölçüm ipucudur. Asla özgün içeriği yeniden oluşturmak için kullanılmamalıdır.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Bu sürümden itibaren
FontRegistryInterface	arayüz	register(), get(), has(), all(), addFontDirectory(), warmup(), lock(), isLocked(), registerBase14(), registerFromBinary(), memoryUsage()	stable	1.7.0
TextPreprocessorInterface	arayüz	process(string): TextPreprocessResult	stable	1.9.0
TextPreprocessResult	final readonly class	$segments, hasRedactions(), getDisplayText()	stable	1.9.0
TextSegment	final readonly class	$displayText, $isRedacted, $originalCharCount, $fillColor	stable	1.9.0

TextPreprocessResult ve TextSegment, yapıcı imzalarını ve genel özelliklerini dondurur; yeni yöntemler eklenebilir, ancak özellikler değiştirilemez.

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

examples/04-text-and-fonts.php

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Bold heading', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Body text rendered with a registered font.');
$doc->save(__DIR__ . '/output/04-text-and-fonts.pdf');

setFont() aileyi FontRegistryInterface üzerinden çözer. Bağımsız bir belge, özel bir kayıt defteri kullanır. Bir çalışan içinde tek bir kayıt defterini paylaşın; belge sayfasına bakın.

Kod örneği — üretim

examples/contracts/typography-production.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\TextPreprocessorInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class FontWarmupService
{
    public function __construct(
        private FontRegistryInterface $fonts,
        private TextPreprocessorInterface $preprocessor,
        private LoggerInterface $logger,
    ) {}

    /**
     * Warm a font set at boot, then lock the registry.
     *
     * @param list<string> $fontFiles Absolute paths to font files.
     */
    public function boot(array $fontFiles): void
    {
        try {
            $this->fonts->warmup($fontFiles);
            $this->fonts->lock();
        } catch (NextPdfException $e) {
            $this->logger->error('Font warmup failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }

    public function redact(string $text): string
    {
        $result = $this->preprocessor->process($text);

        return $result->hasRedactions()
            ? $result->getDisplayText()
            : $text;
    }
}

warmup() ardından lock() çağrısı, çalışan önyükleme dizisidir. lock() sonrasında değişiklik girişimleri istisna fırlatır. Arama işlemleri trafiği karşılamaya devam eder.

Uç durumlar ve dikkat edilecekler

• Kilitli bir kayıt defteri her değişiklik yöntemini reddeder. Kayıt defterini önyükleme sırasında ısıtın ve kilitleyin; istek işleme sırasında asla register() çağırmayın.
• registerFromBinary(), ayrıştırmadan önce yazı tipi baytlarını geçici bir dosyaya yazar. Güvenilmeyen yazı tipi verileri, ayrıştırıcı için bir saldırı yüzeyidir — bunu bir ExternalResourcePolicyInterface üzerinden geçirin (güvenlik politikası sayfasına bakın).
• Bir TextPreprocessor satır sonu, satır başı veya sekme eklememelidir. Bu karakterler yerleşimi değiştirir ve sözleşmenin ilk değişmez kuralını bozar.
• TextSegment::$originalCharCount yalnızca bir genişlik ipucudur. Bunu özgün içeriği çıkarsamak için kullanmak gizlemeyi etkisiz kılar ve sözleşmenin üçüncü değişmez kuralını ihlal eder.
• TextPreprocessResult::getDisplayText(), kara kutu segmentleri için tasarım gereği boş bir dize döndürür. Boş bir segmenti ön işleme hatası olarak görmeyin.

Performans

İlk kullanımda baskın maliyet yazı tipi ayrıştırmadır; kayıt defteri bu maliyeti süreç başına bir kez amortize eder. Isıtmadan sonra get() ve has(), O(1) eşleme aramalarıdır. memoryUsage(), bir çalışanın yazı tipi önbelleğini bütçesine karşı izleyebilmesi için bir MemoryReport döndürür. Metin ön işleme, giriş uzunluğuna göre doğrusaldır. Segment listesi, gizleme eşleşmelerinin sayısıyla orantılı, sınırlı bir ek yük getirir. 1500 ms duvar süresi ve 64 MB tepe bellek değerindeki performance_budget, tipik bir yazı tipi seti için ısıtmayı ve belge işlemeyi kapsar. Alt kümeleme maliyeti, yazı tipinin tam glif tablosuyla değil, gerçekten kullanılan glif sayısıyla ölçeklenir. Bu nedenle alt kümeleme, CJK içeriği için çıktı boyutunu ve işleme maliyetini azaltır.

Güvenlik notları

Tipografi alanının güvenlik açısından iki önemli yüzeyi vardır. Birincisi, yazı tipi girdisidir: registerFromBinary() rastgele baytları ayrıştırır. Güvenilmeyen yazı tipi verileri, ayrıştırıcıya ulaşmadan önce dosya boyutunu ve glif sayısını sınırlayan bir ExternalResourcePolicyInterface politikasından geçmelidir. İkincisi, gizlemedir: TextPreprocessorInterface, glif yerleşiminden, yazı tipi alt kümelemesinden, ToUnicode CMap’ten ve yapı ağacından önce çalışır; böylece gizlenmiş içerik oluşturulan yapıta asla girmez. Boyama zamanında uygulanan bir kaplama gizlemesi, özgün metni içerik akışında ve alt kümede sızdırır. Sözleşmenin konumlandırması bu kusur sınıfını önler. Bir segmentteki ölçüm ipucu kasıtlı olarak geri döndürülemezdir. Dışarıdan sağlanan herhangi bir yazı tipini veya metni güvenilmez olarak değerlendirin.

Uyumluluk

İddia	Standart	Madde	Kanıt
Belgenin kullandığı her yazı tipi gömülür; böylece belge sistem yazı tiplerine güvenmeden işlenir.	ISO 32000-2	§9
Gömülü yazı tipi, belgenin başvurduğu gliflerle sınırlı bir alt kümeye ayrılır.	ISO 32000-2	§9

Her iki madde de özetlenerek aktarılmıştır. NextPDF normatif metni yeniden üretmez. PDF/A-4, her yazı tipi için gömmeyi zorunlu kılar. Bu uyumluluk, çıkarma ve erişilebilirlik sayfalarında belgelenmiştir.

Ayrıca bakınız

• Sözleşmeler: 41 genel arayüz (SPI) — hizmet sağlayıcı arayüzüne genel bakış ve kararlılık katmanları.
• Sözleşmeler / Belge — belge yaşam döngüsünde kayıt defterinin rolü.
• Sözleşmeler / Güvenlik Politikası — güvenilmeyen yazı tipi baytlarını denetleyen ExternalResourcePolicyInterface.
• Tipografi — metin biçimlendirme ve yerleşim modülü.
• Font — yazı tipi ayrıştırma, alt kümeleme ve gömme.
• Text — ön işlemci sonuçlarını tüketen metin çıktısı.