kararlılık: Deneysel

Karmaşık betik şekillendirme desteği

Bir bakışta

Katılımlı önizleme. Karmaşık betik şekillendirmesi varsayılan olarak kapalıdır. Kapalıyken motor, mevcut kod-noktasından-cmap’e yolu üzerinden işler — özelliği içermeyen bir derlemeyle bayt düzeyinde özdeş. Bunu yalnızca libharfbuzz ve şekillendirme yeteneğine sahip bir yazı tipiniz olduğunda açın ve sonucu doğrulayın.

HTML işleyicisi, Tibetçe ve Moğolca için katılımlı bir karmaşık betik şekillendiricisi ekler. Şekillendirici açık olduğunda, saptanan kapsam içi bir Tibetçe ya da Moğolca çalışması libharfbuzz üzerinden şekillendirilir ve Identity-H glif kodları olarak yayılır. Şekillendirici, kaydırma dahil olmak üzere TrueType ve CFF/OTTO yüzlerindeki yatay Tibetçeyi ve yukarıdan aşağıya (TTB) ayarlanan dikey Moğolcayı kapsar.

Kurulum

composer require nextpdf/core:^3

Şekillendirici core paketiyle birlikte gelir. CssFeatureFlags::$complexTextShaping katılımı @since 6.1.0 şeklindedir. Bayrak açıkken libharfbuzz bir çalışma zamanı gereksinimidir — şekillendirici, PHP’nin FFI eklentisi üzerinden libharfbuzz çağırır. Bayrak kapalıyken kitaplığın libharfbuzz bağımlılığı yoktur.

Kavramsal genel bakış

Karmaşık betikler glifleri bağlama göre yeniden sıralar, değiştirir ve yeniden konumlandırır. Saf bir kod-noktasından-glife eşlemesi onları görünür biçimde yanlış işler. Şekillendirici, kapsam içi bir çalışmayı, yazı tipinin OpenType şekillendirme tablolarını uygulayan libharfbuzz’a verir ve motor, ortaya çıkan glif dizisini Identity-H kodlamalı bileşik bir Type 0 yazı tipi olarak yayar (ISO 32000-2 §9.7.4 — gösterilen dize iki baytlık CID’lerdir).

Kapsam kasıtlıdır. Şekillendirici Tibetçe ve Moğolca çalışmaları tanır ve şekillendirir; genel karmaşık betik kapsamı iddia etmez. Yatay Tibetçe, satır kaydırmasıyla birlikte TrueType ve CFF/OTTO yüzlerinde şekillendirilir. Moğolca, yukarıdan aşağıya dikey olarak şekillendirilir.

Hata-durumunda-kapalı sınırı — katı ve türlenmiş

Şekillendirici, geri dönüş olarak asla şekillendirilmemiş, görsel olarak bozuk glifler yaymaz. Aslına uygun şekillendirilemeyen bir çalışma bunun yerine türlenmiş bir istisna yükseltir:

ComplexScriptShapingException — çalışma aslına uygun şekillendirilemez: yazı tipinde gereken glifler eksiktir (bir .notdef ortaya çıkar), bir CFF yüzünden dikey yolda şekillendirme istenmiştir, çalışma bir bağlantı içerir ya da bir Moğolca sütun kaydırmaya ihtiyaç duyar (kapsam dışı bir durum).
HarfBuzzUnavailableException — bayrak açıktır ama libharfbuzz çalışma zamanında FFI üzerinden erişilebilir değildir.

Bayrak kapalıyken, kapsam içi bir çalışma mevcut kod-noktasından-cmap’e yolu üzerinden işlenir. Bu, bir şekillendirme iddiası değil, belgelenmiş bir sınırlamadır: kapalı yol OpenType şekillendirmesi uygulamaz; bu nedenle bağlamsal biçimler garanti edilmez. Kapalı yol çıktısını “şekillendirilmiş” olarak nitelemeyin.

Dürüstlük sınırı — nesnel eşlik, estetik onay değil

Şekillendirme aslına uygunluğu, HarfBuzz’a karşı nesnel olarak doğrulanır: yayılan glif tanımlayıcıları, küme eşlemesi ve glif konumları HarfBuzz başvuru çıktısıyla eşleşir (glif, küme ve konum eşliği). Bir anadili konuşan estetik incelemesi — sonucun akıcı bir okuyucuya doğal okunup okunmadığını yargılamak — sürümden sonraya izlenen bir takip işidir. NextPDF bu API’de ya da bu belgelerde hiçbir dil-kalitesi iddiasında bulunmaz. Nesnel eşlik öne sürülür; estetik kalite öne sürülmez.

API yüzeyi

Simge	Konum	Rol
`CssFeatureFlags::$complexTextShaping`	`src/Html/CssFeatureFlags.php`	Tibetçe/Moğolca şekillendiricisi için katılımlı bayrak (varsayılan `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Bayrak kümesini bir belge yapılandırmasına iliştirir.
`ComplexScriptShapingException`	`src/Font/Shaper/ComplexScriptShapingException.php`	Kapsam içi bir çalışma aslına uygun şekillendirilemediğinde fırlatılır.
`HarfBuzzUnavailableException`	`src/Font/Shaper/HarfBuzzUnavailableException.php`	Bayrak açıkken libharfbuzz kullanılamadığında fırlatılır.

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(complexTextShaping: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>',
);
$doc->save(__DIR__ . '/tibetan.pdf');

Kod örneği — üretim

Şekillendirme yeteneğine sahip bir yazı tipi kaydedin, şekillendiriciye dahil olun ve iki türlenmiş hata kipini açıkça ele alın. Aslına uygun bir işleme ya da açık bir istisna — asla sessizce bozulmuş bir glif çalışması değil.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\DocumentFactory;
use NextPDF\Exception\ComplexScriptShapingException;
use NextPDF\Exception\HarfBuzzUnavailableException;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Html\Css\CssFeatureFlags;
use NextPDF\Typography\FontRegistry;

$fontRegistry = new FontRegistry();
$fontRegistry->register('/path/to/NotoSerifTibetan-Regular.ttf', alias: 'NotoSerifTibetan');

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(complexTextShaping: true),
);

$factory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $factory->create($config);
$doc->setLanguage('bo');
$doc->addPage();

try {
    $doc->writeHtml('<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>');
} catch (HarfBuzzUnavailableException $e) {
    // The flag is on but libharfbuzz is not reachable. Install it, or turn the
    // flag off to fall back to the unshaped cmap path.
    throw $e;
} catch (ComplexScriptShapingException $e) {
    // The run cannot be shaped faithfully (missing glyphs, link in run,
    // out-of-scope case). Fix the font or the content; do not ship broken glyphs.
    throw $e;
}

$doc->save($out);

Sınır durumları ve dikkat edilmesi gerekenler

Açıkken libharfbuzz gereklidir. Bayrak açık ve libharfbuzz yokken motor HarfBuzzUnavailableException fırlatır. Sessizce bozulmaz.
Kapalı “şekillendirilmiş” değildir. Bayrak kapalıyken kapsam içi bir çalışma, OpenType şekillendirmesi olmadan cmap yolu üzerinden işlenir. Bu, belgelenmiş bir sınırlamadır; buna şekillendirilmiş çıktı demeyin.
Kapsam Tibetçe ve Moğolcadır. Diğer karmaşık betikler bu dilim için kapsam dışıdır.
Çalışmadaki bir bağlantı hata durumunda kapalı kalır. Bir bağlantı ek açıklaması içeren bir çalışma ComplexScriptShapingException yükseltir; çünkü bağlantı dikdörtgeni, şekillendirilmiş yeniden sıralamayı izleyemez.
Dil-kalitesi iddiası yok. HarfBuzz ile eşlik öne sürülür; anadili konuşan estetik kalitesi izlenen bir takip işidir ve iddia edilmez.

Performans

Şekillendirme, kapsam içi çalışma başına bir libharfbuzz çağrısı, artı glif-yayma geçişini ekler; glif sayısında doğrusaldır. Bütçe (wall_ms: 2000, peak_mb: 128) CJK/karmaşık-betik profilini izler; çünkü şekillendirme yazı tipleri büyüktür ve yazı tipi işleme maliyete egemendir.

Güvenlik notları

Şekillendiriciyi etkinleştirmek, yerel bir kitaplık olan libharfbuzz’a bir FFI çağrısı getirir. Yazı tipi dosyaları, şekillendiriciye ulaşmadan önce tipografi katmanının mevcut doğrulamasınca işlenen güvenilmez ikili giriş olarak kalır. Şekillendirici zaten kayıtlı, zaten doğrulanmış yüzleri tüketir. Son kullanıcının sağladığı yazı tiplerinin kaynağını güvenilmez olarak ele alın ve libharfbuzz’u güvenilir bir kaynaktan sağlayın.

Uygunluk

İfade	Standart	Madde
Şekillendirilen çalışmalar, bileşik bir Type 0 yazı tipinde Identity-H iki baytlık CID’ler olarak yayılır.	ISO 32000-2	§9.7.4
Şekillendirici, yazı tipinin OpenType glif değiştirme ve konumlandırmasını uygular.	OpenType Specification	GSUB / GPOS
Küme oluşumu, Tibetçe ve Moğolca için betik özelliklerini izler.	Unicode Standard Annex	Tibetan and Mongolian

Bu, Tibetçe ve Moğolca ile sınırlandırılmış, nesnel HarfBuzz eşliği için doğrulanmış bir önizleme uygulamasıdır. Hiçbir dil-kalitesi iddiasında bulunmaz ve üretilen dosya için uçtan uca hiçbir PDF uygunluğu öne sürmez. Hiçbir standart metin olduğu gibi aktarılmaz.