Fon: tipe nilai, penyematan, dan fallback

Sekilas pandang

Di NextPDF, fon adalah objek nilai imutabel FontInfo beserta tipe teknologi yang memberi tahu mesin cara menyematkannya. Mesin menyematkan setiap fon yang digunakan. Referensi Base 14 lama menggunakan fallback ke substitusi bawaan yang kompatibel secara metrik.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

FontInfo adalah objek nilai imutabel yang memberi mesin semua hal yang dibutuhkan untuk menyematkan fon: keluarga dan gaya, nama PostScript, flag deskriptor, metrik yang diskalakan ke em 1000-unit, lebar karakter, peta glif-ke-Unicode, peta karakter maju (cmap, Unicode ke pengidentifikasi glif), byte fon mentah, dan, jika ada, sumbu variasi, instans bernama, pemilih variasi, pasangan kern, serta metrik vertikal. Objek ini bersifat final readonly. Tanda tangan konstruktor dan properti publiknya dibekukan, sehingga fon yang telah diurai menjadi fakta stabil yang dapat dibagikan. FontInfo::encodeText() adalah satu-satunya metode yang memiliki perilaku. Metode ini meneruskan proses melalui resolver pengodean dan mengembalikan sebuah EncodedGlyphRun.

FontType mencantumkan teknologi yang disematkan mesin: TrueType (pengodean satu-byte), TrueTypeUnicode (pengodean pengidentifikasi karakter (CID) multi-byte untuk aksara yang kaya Unicode), OpenType (kerangka Compact Font Format), Type1 (PostScript Type 1, didaftarkan dari pasangan Printer Font Binary (PFB) dan Adobe Font Metrics (AFM)), dan CidFont0 (fon CID berbasis PostScript). Tipe yang ditetapkan parser menentukan bentuk kamus fon yang dihasilkan penulis.

Agar proses render tetap independen dari fon sistem yang terpasang, mesin menyematkan program fon — ISO 32000-2 §9. Program TrueType disematkan melalui entri deskriptor fon FontFile2 dan harus menyertakan tabel glyf, head, hhea, hmtx, loca, dan maxp — ISO 32000-2 §9.6.5 (digest RAG terpotong oleh batas lisensi; tercatat dalam _downgraded-claims-o3.md). Program OpenType dengan tabel kerangka Compact Font Format disematkan melalui FontFile3 — ISO 32000-2 §9.6.5 (digest RAG terpotong; lihat log yang sama). Subsetter membangun ulang kumpulan tabel wajib ini secara persis, sehingga subset yang disematkan tetap menjadi program yang sesuai standar.

Fallback mencakup kasus Base 14 lama. Base14SubstituteFonts memetakan kunci Base 14 yang ternormalisasi — helvetica, helveticab, times, courier, dan selebihnya — ke berkas Liberation Fonts bawaan. Liberation Sans, Serif, dan Mono kompatibel secara metrik dengan Helvetica atau Arial, Times Roman, dan Courier. Masing-masing adalah wajah TrueType yang disematkan, sehingga merender seluruh repertoar Latin WinAnsiEncoding (Windows-1252) yang dipersyaratkan oleh referensi standard-14 — Latin beraksen, tanda Euro, serta tanda baca tipografis umum (ISO 32000-2 Annex D.2). Symbol dan ZapfDingbats tidak memiliki pengganti kompatibel-metrik dengan lisensi permisif, sehingga NextPDF sengaja tidak menggantinya; dokumen yang membutuhkan salah satu fon tersebut harus mendaftarkan fon yang dapat disematkan. Resolver tidak memiliki efek samping: ia hanya menjawab berkas mana yang dipetakan oleh suatu kunci. Pemanggil tetap bertanggung jawab atas pendaftaran ke registri, sambil mempertahankan semantik kunci dan pipeline pemanasan.

Permukaan API

Tipe	Jenis	Anggota utama	Stabilitas	Sejak
FontInfo	kelas final readonly	$family, $style, $type, $unitsPerEm, $widths, $unicodeMap, $cmapForward, $fileData, $variationAxes, $kernPairs, getKey(), encodeText()	stabil	1.0.0
FontType	enum (string)	TrueType, TrueTypeUnicode, OpenType, Type1, CidFont0	stabil	1.0.0
Base14SubstituteFonts	kelas final (internal)	pemetaan kunci Base 14 ternormalisasi ke jalur berkas Liberation bawaan	stabil	2.7.0
ShaperFactory	kelas final	default(), create(), wouldUseRealShaper()	stabil	3.2.0
ShapingResult	kelas final readonly	$glyphRuns, $originalText, $script, $direction, $shaperImpl	stabil	3.2.0

Base14SubstituteFonts bersifat @internal: digunakan oleh framework saja, tanpa jaminan kompatibilitas mundur untuk permukaannya.

Contoh kode — Mulai cepat

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);

Parser mengisi FontInfo dan menetapkan FontType. Wajah TrueType dengan peta karakter Unicode menjadi TrueTypeUnicode, yang dihasilkan penulis sebagai fon komposit Type 0.

Contoh kode — Produksi

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);
        }
    }
}

Resolver tidak memiliki efek samping. Pendaftaran tetap eksplisit, sehingga kontrak kunci dan pemanasan registri tetap terjaga. Symbol dan ZapfDingbats sengaja tidak mengembalikan jalur.

Kasus khusus & jebakan

• Symbol dan ZapfDingbats sengaja tidak digantikan. Nilai null untuk kunci-kunci tersebut adalah perilaku yang terdokumentasi, bukan bug fon yang hilang.
• FontInfo bersifat final readonly. Perlakukan fon yang diurai sebagai sebuah nilai: jangan pernah mengandalkan mutasi langsung pada lebar atau metriknya; daftarkan ulang jika sumbernya berubah.
• Fon Type 1 membutuhkan kerangka PFB sekaligus metrik AFM. FontRegistry::registerType1() menerima pasangan tersebut; penemuan otomatis memperoleh jalur AFM dari jalur PFB berdasarkan ekstensi.
• FontType::TrueType dan FontType::TrueTypeUnicode menandai perbedaan antara satu-byte dan multi-byte. Resolver pengodean menggunakan peta karakter maju yang terisi, bukan nama keluarga, sehingga wajah TrueType Unicode otomatis diarahkan ke jalur Identity-H.
• Sumbu variasi fon dan instans bernama diurai ke dalam FontInfo jika ada, tetapi contoh Tionghoa, Jepang, dan Korea (CJK) yang disajikan sengaja menggunakan wajah statis untuk menjaga FontInfo hasil uraian tetap deterministik.

Performa

Registri mengalokasikan FontInfo sekali per fon per proses, lalu membagikannya melalui referensi. Byte fon mentah mendominasi biaya memori. Lakukan pemanasan hanya pada fon yang dibutuhkan worker dan lacak memoryUsage(). Resolver substitusi Base 14 melakukan pencarian pada peta dalam waktu konstan tanpa input/output (I/O) hingga pemanggil mendaftarkan berkas hasil resolusi. performance_budget sebesar 1500 ms wall dan puncak 64 MB mencakup pemanasan kumpulan fon umum ditambah proses render. Sebelum subsetter berjalan, jejak memori setiap fon berskala dengan ukuran berkas fon, bukan jumlah glif.

Catatan keamanan

FontInfo itu sendiri bersifat inert: data hasil uraian tidak memiliki perilaku selain transformasi murni encodeText(). Permukaan serangan berada di hulu, pada saat penguraian, ketika byte fon arbitrer masuk ke parser TrueType atau Type 1. Parser memeriksa batas setiap offset biner dan menolak stream wrapper serta byte null pada jalur. Sebelum pendaftaran, masukan fon yang tidak tepercaya harus lolos kebijakan sumber daya eksternal yang membatasi ukuran dan jumlah glif. Substitusi Liberation bawaan adalah aset tepercaya yang dikirimkan bersama paket, sehingga jalur fallback tidak memperkenalkan masukan tak tepercaya yang baru.

Kesesuaian

Klaim	Standar	Klausa	Bukti
Setiap fon yang digunakan dokumen disematkan, sehingga dokumen tersebut dirender tanpa bergantung pada fon sistem.	ISO 32000-2	§9
Program TrueType disematkan melalui FontFile2 dengan tabel glyf, head, hhea, hmtx, loca, maxp.	ISO 32000-2	§9.6.5	Digest RAG terpotong oleh batas lisensi; prefiks 7b26f37996239b2a, lihat _downgraded-claims-o3.md
Program OpenType (CFF) disematkan melalui FontFile3.	ISO 32000-2	§9.6.5	Digest RAG terpotong oleh batas lisensi; prefiks 801549ee00623baf, lihat _downgraded-claims-o3.md

Klausa pertama di-pin dengan digest dan dikuatkan oleh B1. Klausa FontFile2 dan FontFile3 merupakan parafrasa. Digest RAG penuh untuk klausa-klausa tersebut tidak dikembalikan (pemotongan akibat batas lisensi), sehingga buktinya juga dikuatkan oleh FontSubsetter (yang membangun ulang persis kumpulan glyf/head/hhea/hmtx/loca/maxp) dan enum FontType. NextPDF tidak mereproduksi teks normatif. Dalam kode sumber, Base14SubstituteFonts mengutip ISO 32000-2 §9.6.2.2 (penanganan fon Type 1 standar), ISO 14289-2:2024 §8.4.5.5.1 (penyematan fon PDF/UA-2), dan ISO 19005-4:2020 §6.3.5 (penyematan fon PDF/A-4). Halaman aksesibilitas dan kesesuaian memuat kesesuaian profil yang lengkap.

Konteks komersial

Paket lisensi fon komersial dan layanan subsetting dinamis dibangun di atas FontInfo Core dan registrinya. Modul fon Core menyematkan, melakukan subsetting, dan menyediakan fallback tanpa lisensi. Tautan konversi yang dihilangkan memang disengaja.

Lihat juga

• Typography: registry, subsetting, CMap, encoding, BiDi — alur kerja registri dan subsetting yang menghasilkan serta mengonsumsi FontInfo.
• Text: shaping, breaking, BiDi — lapisan shaping yang mengonsumsi run hasil pengodean.
• Contracts / Typography — kontrak FontRegistryInterface.