Yazı tipi: değer türleri, gömme ve yedekler

Bir bakışta

NextPDF’te yazı tipi, değişmez FontInfo değer nesnesiyle ve motora yazı tipini nasıl gömeceğini bildiren teknoloji türüyle temsil edilir. Motor, kullandığı her yazı tipini gömer. Eski bir Base 14 başvurusu, paketle birlikte gelen ve metrikleri uyumlu olan bir yedeğe düşer.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

FontInfo, bir yazı tipini gömmek için motorun ihtiyaç duyduğu her şeyi sağlayan değişmez değer nesnesidir: aile ve stil, PostScript adı, tanımlayıcı bayrakları, 1000 birimlik em’e ölçeklenmiş metrikler, karakter genişlikleri, glif-Unicode eşlemesi, ileri karakter eşlemesi (cmap, Unicode’dan glif tanımlayıcısına), ham yazı tipi baytları ve mevcut olduğunda varyasyon eksenleri, adlandırılmış örnekler, varyasyon seçicileri, kern çiftleri ve dikey metrikler. final readonly niteliğindedir. Yapıcı imzası ve public özellikleri dondurulmuştur; bu nedenle ayrıştırılmış bir yazı tipi, kararlı ve paylaşılabilir bir olgu olarak kalır. Davranış içeren tek yöntem FontInfo::encodeText() yöntemidir. Kodlamayı çözümleyici üzerinden yürütür ve bir EncodedGlyphRun döndürür.

FontType, motorun gömdüğü teknolojileri sıralar: TrueType (tek baytlı kodlama), TrueTypeUnicode (Unicode kapsamı geniş yazı sistemleri için çok baytlı karakter tanımlayıcısı (CID) kodlaması), OpenType (Compact Font Format ana hatları), Type1 (PostScript Type 1, bir Printer Font Binary (PFB) ve Adobe Font Metrics (AFM) çiftinden kaydedilir) ve CidFont0 (PostScript tabanlı bir CID yazı tipi). Ayrıştırıcı tarafından atanan tür, PDF üreticisinin oluşturduğu yazı tipi sözlüğünün şeklini belirler.

İşlemeyi kurulu sistem yazı tiplerinden bağımsız tutmak için motor, yazı tipi programını gömer — ISO 32000-2 §9. Bir TrueType programı, FontFile2 yazı tipi tanımlayıcı girdisi aracılığıyla gömülür ve glyf, head, hhea, hmtx, loca ve maxp tablolarını içermelidir — ISO 32000-2 §9.6.5 (RAG özeti lisans sınırı nedeniyle kesildi; _downgraded-claims-o3.md dosyasına kaydedildi). Compact Font Format ana hat tablosuna sahip bir OpenType programı, FontFile3 aracılığıyla gömülür — ISO 32000-2 §9.6.5 (RAG özeti kesildi; aynı günlüğe bakın). Alt küme oluşturucu tam olarak bu gerekli tablo kümesini yeniden oluşturur; böylece gömülü alt küme, uyumlu bir program olarak kalır.

Yedek mekanizması, eski Base 14 durumunu kapsar. Base14SubstituteFonts, normalleştirilmiş bir Base 14 anahtarını — helvetica, helveticab, times, courier ve diğerlerini — paketle birlikte gelen bir Liberation Fonts dosyasına eşler. Liberation Sans, Serif ve Mono, sırasıyla Helvetica veya Arial, Times Roman ve Courier ile metrik uyumludur. Bunların her biri gömülü bir TrueType yüzüdür; bu nedenle standart-14 başvurusunun gerektirdiği tam WinAnsiEncoding (Windows-1252) Latin repertuvarını işler — aksanlı Latin, Euro işareti ve yaygın tipografik noktalama (ISO 32000-2 Annex D.2). Symbol ve ZapfDingbats için izinli lisansa sahip, metrik uyumlu bir karşılık bulunmadığından NextPDF bunları bilinçli olarak yerine koymaz; bu yazı tiplerinden birine ihtiyaç duyan bir belge, gömülebilir bir yazı tipi kaydetmelidir. Çözümleyicinin hiçbir yan etkisi yoktur: yalnızca bir anahtarın hangi dosyaya eşlendiğini döndürür, başka hiçbir şey yapmaz. Kilitleme semantiğini ve ısınma işlem hattını koruyarak kayıt defterine kayıt yapma sorumluluğu çağırana aittir.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Sürümden beri
FontInfo	final readonly sınıf	$family, $style, $type, $unitsPerEm, $widths, $unicodeMap, $cmapForward, $fileData, $variationAxes, $kernPairs, getKey(), encodeText()	kararlı	1.0.0
FontType	enum (string)	TrueType, TrueTypeUnicode, OpenType, Type1, CidFont0	kararlı	1.0.0
Base14SubstituteFonts	final sınıf (dahili)	normalleştirilmiş Base 14 anahtarından paketle gelen Liberation dosya yoluna eşleme	kararlı	2.7.0
ShaperFactory	final sınıf	default(), create(), wouldUseRealShaper()	kararlı	3.2.0
ShapingResult	final readonly sınıf	$glyphRuns, $originalText, $script, $direction, $shaperImpl	kararlı	3.2.0

Base14SubstituteFonts, @internal niteliğindedir: yalnızca framework içinde kullanım içindir ve API yüzeyi için geriye dönük uyumluluk garantisi yoktur.

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

examples/35-cjk-cmap-demo.php

<?php

declare(strict_types=1);

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

use NextPDF\Typography\FontRegistry;
use NextPDF\Typography\FontType;

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

// FontInfo is the immutable parsed fact about the face.
echo $font->family, ' / ', $font->type->value, "\n"; // e.g. "Noto Sans TC / TrueTypeUnicode"
assert($font->type === FontType::TrueTypeUnicode);

Ayrıştırıcı, FontInfo nesnesini doldurur ve FontType değerini atar. Unicode karakter eşlemesine sahip bir TrueType yüzü TrueTypeUnicode olur ve PDF üreticisi bunu bir Type 0 bileşik yazı tipi olarak üretir.

Kod örneği — üretim

examples/font/base14-fallback.php

<?php

declare(strict_types=1);

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

use NextPDF\Typography\Base14SubstituteFonts;
use NextPDF\Typography\FontRegistry;

final readonly class Base14EmbeddingResolver
{
    public function __construct(private FontRegistry $registry) {}

    /**
     * Register an embeddable substitute for a legacy Base 14 key so the
     * output document embeds every font (PDF/A-4 and PDF/UA-2 require it).
     */
    public function ensureEmbeddable(string $base14Key): void
    {
        $path = Base14SubstituteFonts::resolve($base14Key);

        if ($path === null) {
            // Symbol / ZapfDingbats have no permissive substitute — the
            // caller must supply its own embeddable font.
            throw new \RuntimeException("No bundled substitute for {$base14Key}");
        }

        if (!$this->registry->has($base14Key)) {
            $this->registry->register($path, alias: $base14Key);
        }
    }
}

Çözümleyicinin hiçbir yan etkisi yoktur. Kayıt işlemi açık kalır; böylece kayıt defterinin kilitleme ve ısınma sözleşmeleri geçerliliğini korur. Symbol ve ZapfDingbats tasarım gereği hiçbir yol döndürmez.

Uç durumlar ve tuzaklar

• Symbol ve ZapfDingbats kasıtlı olarak yerine konmaz. Bu anahtarlar için null sonucu, eksik yazı tipi hatası değil, belgelenmiş davranıştır.
• FontInfo, final readonly niteliğindedir. Ayrıştırılmış bir yazı tipini bir değer olarak ele alın: genişlikleri veya metrikleri yerinde değiştirebileceğinizi asla varsaymayın; kaynak değişirse yeniden kaydedin.
• Bir Type 1 yazı tipi hem PFB ana hattına hem de AFM metriklerine ihtiyaç duyar. FontRegistry::registerType1() bu çifti alır; otomatik bulma, AFM yolunu PFB yolundan uzantıya göre türetir.
• FontType::TrueType ve FontType::TrueTypeUnicode tek baytlı ile çok baytlı arasındaki ayrımı belirtir. Kodlama çözümleyicisi, aile adını değil, doldurulmuş ileri karakter eşlemesini kullanır; bu nedenle bir Unicode TrueType yüzü otomatik olarak Identity-H yoluna yönlendirilir.
• Varyasyon yazı tipi eksenleri ve adlandırılmış örnekler, mevcut olduğunda FontInfo içine ayrıştırılır; ancak şekillendirilmiş Çince, Japonca ve Korece (CJK) örneği, ayrıştırılmış FontInfo nesnesini deterministik tutmak için bilinçli olarak statik yüzü kullanır.

Performans

Kayıt defteri, FontInfo nesnesini işlem başına her yazı tipi için bir kez ayırır, ardından bunu referansla paylaşır. Bellek maliyetine ham yazı tipi baytları hâkimdir. Yalnızca bir işçinin ihtiyaç duyduğu yazı tiplerini ısıtın ve memoryUsage() değerini izleyin. Base 14 yedek çözümleyicisi, çağıran çözümlenmiş dosyayı kaydedene kadar hiçbir girdi/çıktı (I/O) yapmadan sabit zamanlı bir eşleme araması yapar. 1500 ms duvar saati süresi ve 64 MB tepe değerindeki performance_budget değeri, tipik bir yazı tipi kümesi ısınmasını ve işlemeyi kapsar. Alt küme oluşturucu çalışana kadar, her yazı tipinin bellek ayak izi glif sayısıyla değil, yazı tipi dosyası boyutuyla ölçeklenir.

Güvenlik notları

FontInfo nesnesinin kendisi etkisizdir: saf encodeText() dönüşümü dışında hiçbir davranışı olmayan ayrıştırılmış veridir. Saldırı yüzeyi, keyfi yazı tipi baytları TrueType veya Type 1 ayrıştırıcısına ulaştığında, üst akışta, ayrıştırma zamanında bulunur. Ayrıştırıcılar her ikili ofsetin sınırlarını denetler ve yollardaki stream wrapper’ları ile null baytları reddeder. Kayıttan önce, güvenilmeyen yazı tipi girişi, boyutu ve glif sayısını sınırlayan bir dış kaynak ilkesini geçmelidir. Paketle birlikte gelen Liberation yedekleri, paketle gönderilen güvenilir varlıklardır; bu nedenle yedek yol yeni bir güvenilmeyen giriş getirmez.

Uygunluk

İ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
Bir TrueType programı, FontFile2 aracılığıyla şu tablolarla birlikte gömülür: glyf, head, hhea, hmtx, loca, maxp.	ISO 32000-2	§9.6.5	RAG özeti lisans sınırı nedeniyle kesildi; önek 7b26f37996239b2a, bkz. _downgraded-claims-o3.md
Bir OpenType (CFF) programı, FontFile3 aracılığıyla gömülür.	ISO 32000-2	§9.6.5	RAG özeti lisans sınırı nedeniyle kesildi; önek 801549ee00623baf, bkz. _downgraded-claims-o3.md

İlk madde, özetle sabitlenmiştir ve B1 tarafından desteklenir. FontFile2 ve FontFile3 maddeleri başka sözcüklerle ifade edilmiştir. Bu maddeler için tam RAG özetleri döndürülmedi (lisans sınırı nedeniyle kesildi); bu nedenle kanıt, ayrıca FontSubsetter (tam olarak glyf/head/hhea/hmtx/loca/maxp kümesini yeniden oluşturur) ve FontType enum’u tarafından da desteklenir. NextPDF normatif metni yeniden üretmez. Kaynak kodda Base14SubstituteFonts, ISO 32000-2 §9.6.2.2 (standart Type 1 yazı tipi işleme), ISO 14289-2:2024 §8.4.5.5.1 (PDF/UA-2 yazı tipi gömme) ve ISO 19005-4:2020 §6.3.5 (PDF/A-4 yazı tipi gömme) maddelerine atıfta bulunur. Erişilebilirlik ve uygunluk sayfaları, tam profil uygunluğunu kapsar.

Ticari bağlam

Ticari bir yazı tipi lisanslama paketi ve dinamik bir alt küme oluşturma hizmeti, Core FontInfo ve kayıt defteri üzerine kurulur. Core yazı tipi modülü, lisans olmadan gömme, alt küme oluşturma ve yedeğe düşme işlemlerini yapar. Dönüşüm bağlantısının çıkarılması kasıtlıdır.

Ayrıca bkz.

• Tipografi: kayıt defteri, alt küme oluşturma, CMap, kodlama, BiDi — FontInfo nesnesini üreten ve tüketen kayıt defteri ve alt küme oluşturma iş akışı.
• Metin: şekillendirme, satır kesme, BiDi — kodlanmış glyph run’ı tüketen şekillendirme katmanı.
• Contracts / Typography — FontRegistryInterface sözleşmesi.