Metin: şekillendirme sınırı, CJK ve dizi işleme

Bir bakışta

Metin modülü şekillendirme sınırını tanımlar. 8 bit Unicode Dönüşüm Biçimi (UTF-8) kodlu bir diziyi konumlandırılmış gliflere dönüştüren küçük bir arabirim sunar; uygun olduğunda gerçek bir OpenType arka ucu seçer, hiçbiri yoksa deterministik biçimde yedeğe geçer ve betiğe özgü şekillendiriciler için bir kayıt sağlar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

ShaperInterface, metin yerleşimi işlem hattını bir OpenType şekillendirme motoruna bağlar. Kasıtlı olarak küçük tutulmuştur: tek bir shape() yöntemi bir ShaperInput alır ve bir ShapingResult döndürür. Bu dönüş türü, tüketicilerin gördüğü tek çıktıdır. Uygulamalar şekillendirme motorunun iç ayrıntılarını sızdırmamalıdır; türlendirilmiş dönüş de bu sınırı zorunlu kılar. ShapingResult, GlyphRun kayıtlarının listesini, geri yansıtılan kaynak metni, betik ve yön bilgisini, ayrıca sonucu üreten arka ucu tanımlayan bir shaperImpl etiketini taşır.

Arka uç seçimi açıktır ve yeteneği tahmine başvurmadan bildirir. ShaperFactory tek bir yetenek yoklaması çalıştırır. Ana makinede çalışan bir HarfBuzz bağlaması varsa, create() HarfBuzz destekli şekillendiriciyi döndürür. Aksi takdirde NullShaper döndürülür. NullShaper bir geçişli yedektir. Her Unicode kod noktası için, sıfır ilerleme ve sıfır kaydırma değeriyle yapay bir glif üretir. Gözlemlenebilirliğin yedeği saptayabilmesi için sonucu etiketler ve ilerleme değerlerinin çözümünü yazı tipi ölçümleri modülüne bırakır. Bu yol, tam şekillendirme değil belgelenmiş bir hizmet düşüşüdür. Değiştirme, bitişik harfler, işaret konumlandırma ve bağlamsal biçimler gerçek arka ucu gerektirir. wouldUseRealShaper() tanılama amaçlı bir yüklemdir. Üretim kodu bunun yerine sonucun shaperImpl etiketine göre dallanmalıdır.

Betiğe özgü şekillendirme, paketlenmiş bir uygulama değil bir hizmet sağlayıcı arabirimidir (SPI). ScriptShaperRegistry, bir MongolianShaperInterface veya TibetanShaperInterface arabirimini Uluslararası Standartlaştırma Örgütü (ISO) 15924 betik etiketine göre çözen, PHP Standartları Önerisi 11 (PSR-11) tarzında bir kayıttır. Kayıt, anahtarları büyük/küçük harfe duyarsız biçimde saklar ve betik kodlarının kabul edilebilirliği için tek bir doğruluk kaynağına dayanır. Kayıt ve betik şekillendirici arabirimleri dondurulmuş bir sözleşmedir; bu nedenle bir uzantı, çağrı noktalarına dokunmadan bir Phase-12 sağlayıcısını kaydedebilir. Motor sınırı sağlar; karmaşık betik sağlayıcılarını ise tüketiciler sağlar.

Çince, Japonca ve Korece (CJK) dizi işleme, tipografi kodlama sınırında yer alır. Gömülü bir CJK TrueType yüzü, ISO 32000-2 §9.7.4 kapsamında, Identity-H CMap ve bir CIDFontType2 alt yazı tipiyle bir Type 0 yazı tipi olarak yayılır (geri getirme destekli üretim (RAG) özeti lisans üst sınırıyla kısaltılmıştır; _downgraded-claims-o3.md içinde kayıtlıdır). TrueType programı gömülü olduğunda, Type 2 CIDFont, ISO 32000-2 §9 kapsamında, karakter tanımlayıcılarını CIDToGIDMap girdisi aracılığıyla glif dizinlerine eşler (özet, B1 sözleşme sayfası tarafından sabitlenmiştir). Alt küme oluşturucu özgün glif numaralandırmasını korur; böylece alt küme için bir /CIDToGIDMap /Identity geçerli kalır. CjkFontValidator, aday bir yazı tipi seçilmeden önce o yazı tipinin bir betiğin gereksinim duyduğu Unicode bloklarını kapsayıp kapsamadığını denetler.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Şu sürümden beri
ShaperInterface	arabirim	shape(ShaperInput): ShapingResult	kararlı	3.2.0
ShaperFactory	final class	default(), create(), wouldUseRealShaper()	kararlı	3.2.0
NullShaper	final readonly class	geçişli yedek şekillendirici	kararlı	3.2.0
ShapingResult	final readonly class	$glyphRuns, $originalText, $script, $direction, $shaperImpl	kararlı	3.2.0
ScriptShaperRegistry	final class	registerMongolian(), getMongolian(), hasMongolian() ve Tibetçe karşılıkları	kararlı	3.1.0
CjkFontValidator	final class	validateCoverage(), detectScript(), isCjkCodepoint()	kararlı	1.0.0

Şu yöntem yapısı — register*, get* ve has* — ScriptShaperRegistry ve betik şekillendirici arabirimleri için dondurulmuş bir sözleşmedir. Tasarım gereği, tüketicilere görünen tek şekillendirici çıktısı ShapingResult değeridir.

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

examples/text/shaper-factory.php

<?php

declare(strict_types=1);

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

use NextPDF\Font\Shaper\ShaperFactory;
use NextPDF\Font\Shaper\ShaperImpl;

$factory = ShaperFactory::default();
$shaper = $factory->create();

// Branch on the result tag, not on the concrete class.
$wouldShape = $factory->wouldUseRealShaper()
    ? 'HarfBuzz backend available'
    : 'NullShaper fallback (degraded — no substitution or positioning)';

echo $wouldShape, "\n";

ShaperFactory::default() üretim ortamına yönelik yetenek yoklamasını bağlar. create() seçilen arka ucu fabrikanın ömrü boyunca önbelleğe alır. Yeteneği incelemek için wouldUseRealShaper() yöntemini ve her sonuçtaki shaperImpl etiketini kullanın.

Kod örneği — üretim

examples/text/script-shaper-registry.php

<?php

declare(strict_types=1);

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

use NextPDF\Text\Shaping\MongolianShaperInterface;
use NextPDF\Text\Shaping\ScriptShaperRegistry;

final readonly class ComplexScriptBootstrap
{
    public function __construct(private ScriptShaperRegistry $registry) {}

    /**
     * Register a consumer-supplied Mongolian shaper provider at boot so
     * the layout pipeline can resolve it by ISO 15924 script tag.
     */
    public function register(MongolianShaperInterface $mongolian): void
    {
        $this->registry->registerMongolian($mongolian);
    }

    public function hasMongolian(): bool
    {
        return $this->registry->hasMongolian();
    }
}

Kayıt, karmaşık betik sağlayıcıları için tümleştirme noktasıdır. Motor, sınırı ve dondurulmuş erişimci yapısını sağlar. Moğolca ve Tibetçe uygulamaları tüketiciler tarafından sağlanır.

Uç durumlar ve dikkat edilecekler

• Bir NullShaper sonucunda sıfır ilerleme ve sıfır kaydırma bulunur. Bu konumları doğrudan metin yerleşimine vermeyin. İlerlemeleri yazı tipi ölçümleri modülünden çözün ve yedeği shaperImpl etiketi aracılığıyla saptayın.
• Boş giriş, boş bir dizi değil boş bir glyphRuns listesi üretir. Tüketici yineleme kodunun, sıfır uzunluklu bir dizi için özel bir duruma gereksinimi olmaz.
• ScriptShaperRegistry, Psr\Container\ContainerInterface arabirimini doğrudan uygulamaz; böylece türlendirilmiş erişimciler statik çözümlemede daraltılmış dönüş türlerini korur. Şunları kullanın: getMongolian() ve getTibetan(); genel bir get() değil.
• Betik etiketleri standart ISO 15924 alpha-4 değerine göre eşleştirilir ve büyük/küçük harfe duyarsız biçimde saklanır. Mong veya Tibt geçirin. Harflerin büyüklüğü/küçüklüğü aramayı etkilemez.
• CJK Eklenti B karakterleri Unicode düzlem 2’de yer alır ve alt kümede bir cmap Format 12 alt tablosunu zorunlu kılar. Kodlama yolu bunu işler. Temel çok dilli düzlemin tüm CJK metnini kapsadığını varsaymayın.

Başarım

Yetenek yoklaması her ShaperFactory örneği için bir kez çalışır ve arka uç önbelleğe alınır; böylece yinelenen create() çağrılarının ek maliyeti olmaz. NullShaper, giriş dizisinin kod noktası sayısına göre doğrusaldır ve hiçbir input/output (I/O) işlemi yapmaz. ScriptShaperRegistry çözümlemesi, sabit zamanlı anahtarlı bir aramadır. CjkFontValidator, her kod noktasını sınamak yerine bir adımda örnekler; bu da 20,000 glifli bir CJK yazı tipinde bile kapsam denetimlerini ucuz tutar. 1500 ms duvar saati süresi ve 64 MB tepe bellek değerindeki performance_budget değeri tipik bir çalışmayı kapsar. Gerçek şekillendirmede baskın maliyet OpenType arka ucudur. Yedek etkin olduğunda bu maliyet bu modülün kapsamı dışındadır.

Güvenlik notları

Şekillendirici sınırı bir UTF-8 dizgesi alır. NullShaper, hatalı biçimli UTF-8 verisini hata fırlatmak yerine elinden geldiğince ayrıştırarak tolere eder; çünkü belgelenmiş yedek sözleşmesi zaten “gerçek şekillendirme yok” biçimindedir. Çağıran taraf düşük kaliteli çıktıya zaten hazırlıklıdır. Bayt ofsetli küme sözleşmesi bayt yönelimli uzunluk kullanır; bu, çok baytlı giriş için doğrudur ve kod noktası ofsetli bir küme eşleme kusurunu önler. Var olduğunda gerçek arka uç, üçüncü taraf bir yerel kitaplıktır. Girişini güvenilmez kabul edin ve dizi uzunluğunu yukarı akışta sınırlandırın. Betik şekillendirici kaydı, tüketicinin sağladığı sağlayıcıları saklar. Bu uygulamalar motorun değil, tüketicinin güven sınırı içinde yer alır.

Uyumluluk

İddia	Standart	Madde	Kanıt
Gömülü bir CJK TrueType yüzü, Identity-H CMap ve bir CIDFontType2 alt yazı tipiyle bir Type 0 yazı tipi olarak yayılır.	ISO 32000-2	§9.7.4	Geri getirme destekli üretim (RAG) özeti lisans üst sınırıyla kısaltılmıştır; önek 7a5258772f508e3b, bkz. _downgraded-claims-o3.md
Gömülü bir Type 2 CIDFont, karakter tanımlayıcılarını CIDToGIDMap aracılığıyla glif dizinlerine eşler.	ISO 32000-2	§9

Her iki madde de başka sözcüklerle ifade edilmiştir. İkinci madde özetle sabitlenmiştir (B1 sözleşme sayfasından yeniden kullanılmıştır) ve birinci madde ADR-013 ile cmap kodlayıcısının geliştirici genel bakışı tarafından doğrulanmıştır. NextPDF normatif metni yeniden üretmez. Şekillendirici arka ucu, Taşınabilir Belge Biçimi (PDF) uyumluluğundan bağımsızdır. Buradaki uyumluluk iddiaları, kodlama sınırı tarafından üretilen CJK yazı tipi sözlüğü yayımıyla ilgilidir. ADR-013 ve cmap kodlayıcısının geliştirici genel bakışı, bu yolu daha ayrıntılı biçimde belgeler.

Ticari bağlam

Gelişmiş metin ön işleme işlem hattı ve çıkarma hizmetleri, Core şekillendirici sınırı ile dizi işleme değer türleri üzerine kurulur. Core metin modülü; sınırı, yedeği ve betik şekillendirici kaydını lisans gerektirmeden sağlar. Eksik dönüşüm bağlantısı kasıtlıdır.

Ayrıca bkz.

• Tipografi: kayıt, alt küme oluşturma, CMap, kodlama, BiDi — kodlama sınırı ve çift yönlü metin motoru.
• Font: değer türleri, gömme, yedek — şekillendirici girişinin başvurduğu FontInfo değeri.
• Contracts / Typography — şekillendirmenin yukarı akışındaki metin ön işleyici sözleşmesi.