Font Tools — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für NextPDF Pro Font Tools. Die Oberfläche besteht aus einem Scanner, NextPDF\Pro\FontTools\FontDesubsetter, und zwei unveränderlichen Value Objects, SubsetInfo und DesubsetPlan. Der Scanner liest rohe PDF-Bytes, meldet jeden eindeutigen /BaseFont-Eintrag und kennzeichnet Einträge, die der Subset-Namenskonvention von ISO 32000-2:2020 §9.9.2 folgen. Ein Plan aggregiert die gekennzeichneten Subsets und schätzt die Byte-Kosten für die Wiederherstellung vollständiger Schriftprogramme. Das Modul analysiert und schätzt lediglich; es schreibt niemals ein eingebettetes Schriftprogramm um. Diese Seite beschreibt die öffentliche API, den beobachtbaren Verhaltensvertrag und die Fehlermodi.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einer Lizenzhülle der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und eine Lizenz erwerben.

Kein funktionsspezifisches Lizenz-Flag schützt dieses Modul. Die Font-Tools-Klassen sind verfügbar, sobald nextpdf/pro installiert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
FontDesubsetter	keine	Zustandsloser Scanner über rohe PDF-Bytes	—	—	final; kann über Dokumente hinweg wiederverwendet werden
FontDesubsetter::analyzeSubsets()	string $pdfData	Meldet jeden eindeutigen /BaseFont-Eintrag, Subset oder nicht, gekennzeichnet durch isSubset	list<SubsetInfo>	InvalidArgumentException, wenn eine breitenabgeleitete Subset-Schätzung die namensabgeleitete Vollzahl-Schätzung übersteigt	Scan auf Byte-Ebene; komprimierte Objekt-Streams werden nicht dekodiert
FontDesubsetter::isSubsetFont()	string $baseFontName	Entspricht der Präfix-Konvention aus sechs Großbuchstaben plus +	bool	—	Am Namensanfang verankert
FontDesubsetter::extractSubsetPrefix()	string $baseFontName	Gibt das sechsstellige Subset-Tag zurück	string	—	Leerer String bei Nicht-Subset-Namen
FontDesubsetter::generateDesubsetPlan()	list<SubsetInfo> $subsets	Sammelt Einträge, deren isSubset true ist, und summiert die Größenschätzung	DesubsetPlan	Wirft nicht	Nicht-Subset-Einträge werden stillschweigend übersprungen
SubsetInfo	Konstruktor: $fontName, $baseFont, $subsetGlyphCount, $fullGlyphCount, $isSubset, $encoding	Unveränderliche Beschreibung eines /BaseFont-Eintrags	—	InvalidArgumentException bei negativer Glyphenzahl oder einer Subset-Zahl über der Vollzahl	final readonly; alle Eigenschaften öffentlich
SubsetInfo::subsetPrefix()	keine	Extrahiert das sechsstellige Tag aus fontName	string	—	Leerer String, wenn kein Subset oder das + nicht an Position sechs steht
SubsetInfo::coveragePercent()	keine	Subset-Anteil am vollen Glyphensatz	float in [0.0, 100.0]	—	Gibt 0.0 zurück, wenn fullGlyphCount 0 ist
DesubsetPlan	Konstruktor: list<SubsetInfo> $targets, int $estimatedSizeIncrease	Unveränderlicher De-Subsetting-Plan	—	—	final readonly; alle Eigenschaften öffentlich
DesubsetPlan::count()	keine	Anzahl der anvisierten Schriften	int	—	Entspricht der Länge von targets
DesubsetPlan::totalGlyphsNeeded()	keine	Fehlende Glyphen summiert über alle Ziele	int	—	Summe von fullGlyphCount - subsetGlyphCount je Ziel

Einstiegspunkt-Signaturen

public function analyzeSubsets(string $pdfData): array

public function isSubsetFont(string $baseFontName): bool

public function extractSubsetPrefix(string $baseFontName): string

public function generateDesubsetPlan(array $subsets): DesubsetPlan

public function __construct(
    public string $fontName,
    public string $baseFont,
    public int $subsetGlyphCount,
    public int $fullGlyphCount,
    public bool $isSubset,
    public string $encoding,
)

public function subsetPrefix(): string

public function coveragePercent(): float

public function __construct(
    public array $targets,
    public int $estimatedSizeIncrease,
) {}

public function count(): int

public function totalGlyphsNeeded(): int

Verhaltensvertrag

Scan und Subset-Erkennung

analyzeSubsets() extrahiert /BaseFont-Namens-Tokens aus den rohen Bytes mit einem Musterabgleich auf Byte-Ebene. Doppelte Namen werden zu einem Eintrag zusammengefasst; die Reihenfolge folgt dem ersten Auftreten. Jeder eindeutige Name ergibt ein SubsetInfo, unabhängig davon, ob es sich um ein Subset handelt. Ein Name ist ein Subset, wenn er mit genau sechs ASCII-Großbuchstaben beginnt, gefolgt von +, der Konvention aus §9.9.2. Bei Subset-Namen ist baseFont der Name ohne das sieben Zeichen lange Präfix. Bei gewöhnlichen Namen entspricht baseFont dem fontName. Jeder eindeutige Subset-Name wird als eigener Eintrag gemeldet, entsprechend der Vorgabe aus §9.9.2, Subsets als unabhängige Entitäten zu behandeln.

Encoding-Erkennung

Für jede Schrift durchsucht der Scanner ein begrenztes Byte-Fenster nach dem Auftreten von /BaseFont. Ein /Encoding-Namenseintrag im Fenster gewinnt. Andernfalls wird ein Identity-H- oder Identity-V-Teilstring im Fenster gemeldet. Schlägt beides fehl, meldet der Eintrag Unknown. Encoding-Werte, die in Dictionaries gehalten oder über indirekte Referenzen erreicht werden, melden Unknown.

Glyphen-Bilanzierung

Beide Glyphenzahlen sind Schätzungen. subsetGlyphCount leitet sich aus Breiten-Arrays ab, die nahe dem Schrifteintrag sichtbar sind: ein CIDFont-/W-Array ergibt etwa eine Glyphe pro Breiten-Tripel, und ein /Widths-Array einer einfachen Schrift ergibt eine Glyphe pro numerischem Eintrag. Ist keines der Arrays im Fenster sichtbar, gilt ein kleiner fester Standardwert. Kann das Auftreten von /BaseFont für die Fenstersuche nicht wiedergefunden werden, ist die Zahl 0. fullGlyphCount leitet sich aus Familiennamen-Heuristiken ab: einer Tabelle bekannter lateinischer Familien, einer Menge von CJK-Familiennamen-Indikatoren und andernfalls einer generischen Untergrenze. Das eingebettete Schriftprogramm wird niemals geparst. Die konkreten Tabellen, Fenstergrößen und Konstanten sind Implementierungsdetail, werden nicht veröffentlicht und können sich zwischen Releases ändern.

Planerstellung

generateDesubsetPlan() filtert die Eingabe auf Einträge, deren isSubset true ist. Jedes Ziel trägt seine Zahl fehlender Glyphen, multipliziert mit einer festen Konstante für durchschnittliche Bytes pro Glyphe, zu estimatedSizeIncrease bei. Der Plan ist eine Projektion für Kapazitätsentscheidungen, kein gemessenes Delta. Das Ausführen eines Plans — das Umschreiben von Schriftprogrammen — liegt außerhalb dieses Moduls.

Determinismus

Die gesamte Oberfläche ist eine reine Funktion ihrer Eingabe. Identische Bytes erzeugen identische Ergebnisse. Es gibt keine Zufälligkeit, keinen Netzwerkaufruf und keinen Dateisystemzugriff.

Grenzfälle & Fehlermodi

• Die Konstruktion von SubsetInfo weist ungültige Zustände zurück: eine negative Glyphenzahl oder eine Subset-Zahl über der Vollzahl wirft InvalidArgumentException.
• analyzeSubsets() kann diese Ausnahme in einem Grenzfall weiterreichen: eine Schrift, deren Name einer bekannten Familie entspricht, deren sichtbares Breiten-Array aber eine größere Subset-Schätzung ergibt als die Vollzahl-Angabe der Familie.
• Die Erkennung arbeitet auf der Byte-Repräsentation. /BaseFont-Einträge, die innerhalb komprimierter Objekt-Streams serialisiert sind, sind unsichtbar; dekomprimieren Sie diese Streams vor dem Scannen.
• Einträge, deren /BaseFont-Schlüssel und -Wert durch anderen Leerraum als ein einzelnes Leerzeichen getrennt sind, werden weiterhin erkannt, doch die Fenstersuche je Schrift findet sie nicht wieder. Solche Einträge melden das Encoding Unknown und eine Subset-Glyphenzahl von 0.
• PDF-Namen mit #-escapten Bytes werden in roher escapter Form gemeldet; die Escapes werden nicht dekodiert.
• Doppelte /BaseFont-Namen werden zu einem einzigen Eintrag zusammengefasst. Zwei unterschiedliche Schriftobjekte, die sich einen Namen teilen, sind für diesen Scanner nicht unterscheidbar.
• generateDesubsetPlan() scheitert niemals an Nicht-Subset-Eingaben; Einträge, deren isSubset auf false gesetzt ist, werden einfach aus targets ausgeschlossen.
• Alle Zahlen und estimatedSizeIncrease sind Heuristiken. Behandeln Sie sie nicht als gemessene Werte; verwenden Sie sie ausschließlich für Triage und Kapazitätsplanung.
• In diesem Modul findet keine kryptografische Operation statt, daher gibt es kein FIPS-Modus-spezifisches Verhalten.

Konformität

Aussage	Standard	Klausel
Die Subset-Erkennung entspricht der Subset-Namenskonvention: ein dem BaseFont-Wert vorangestelltes Tag aus sechs Großbuchstaben, gefolgt von +.	ISO 32000-2:2020	§9.9.2
Jeder eindeutige Subset-Name wird unabhängig gemeldet, gemäß der Empfehlung, mehrere Subsets als separate Entitäten zu behandeln.	ISO 32000-2:2020	§9.9.2

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. Dies sind Fähigkeitsaussagen, keine Zertifizierungen. NextPDF besitzt keine Zertifizierung und erteilt keine. Das Modul sichert die Erkennung der Namenskonvention und deterministische Meldung zu; es sichert nicht die Genauigkeit der Glyphenzahl- oder Größenschätzungen zu.

Entwicklungshinweise

• Installation mit composer require nextpdf/pro:^3. Verfügbar seit nextpdf/pro 1.9.0; aktuell in nextpdf/pro 3.1.0.
• FontDesubsetter ist zustandslos. Einmal konstruieren und über Dokumente und Arbeitsstränge hinweg wiederverwenden.
• Übergeben Sie analyzeSubsets() dekomprimierte Bytes, wenn die Subset-Abdeckung wichtig ist; in Objekt-Streams gepackte Schrift-Dictionaries werden andernfalls übersehen.
• Verzweigen Sie über SubsetInfo::isSubset, bevor Sie handeln; die Ergebnisliste enthält absichtlich Nicht-Subset-Schriften zu Inventarzwecken.
• Verwenden Sie DesubsetPlan::totalGlyphsNeeded() und estimatedSizeIncrease, um zu entscheiden, ob De-Subsetting die Dateigröße-Kosten wert ist, bevor Sie vollständige Schriftprogramme beschaffen.
• Das Scannen ist linear in der Eingabelänge mit begrenzten Fenstersuchen je Schrift. Das Modul speichert nichts und sendet keine Telemetrie.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Font Tools (Fähigkeit) — Installation, Schnellstart und Beispiel-Workflows für die Planung.
• Optimizer — Ausführliche Referenz — die verwandte Oberfläche zur Größenreduktion, einschließlich schriftbezogener Optimierung.
• Core-Schriftmodul — Schrifteinbettung und Subsetting während der Dokumenterstellung in NextPDF Core.