Font Tools — Riferimento approfondito

In breve

Questa pagina è il riferimento a livello di contratto per NextPDF Pro Font Tools. La superficie è uno scanner, NextPDF\Pro\FontTools\FontDesubsetter, e due value object immutabili, SubsetInfo e DesubsetPlan. Lo scanner legge i byte PDF grezzi, riporta ogni voce /BaseFont distinta e segnala le voci che seguono la convenzione di denominazione dei subset di ISO 32000-2:2020 §9.9.2. Un piano aggrega i subset segnalati e stima il costo in byte del ripristino dei programmi font completi. Il modulo si limita ad analizzare e stimare; non riscrive mai un programma font incorporato. Questa pagina indica l’API pubblica, il contratto di comportamento osservabile e le modalità di errore.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Nessun flag di licenza per singola funzionalità applica un gate a questo modulo. Le classi di Font Tools sono disponibili ogni volta che nextpdf/pro è installato.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
FontDesubsetter	nessuno	Scanner senza stato sui byte PDF grezzi	—	—	final; riutilizzabile in sicurezza tra documenti
FontDesubsetter::analyzeSubsets()	string $pdfData	Riporta ogni voce /BaseFont distinta, subset o meno, segnalata da isSubset	list<SubsetInfo>	InvalidArgumentException quando una stima del subset derivata dalle larghezze supera la stima del conteggio completo derivata dal nome	Scansione a livello di byte; gli object stream compressi non vengono decodificati
FontDesubsetter::isSubsetFont()	string $baseFontName	Confronta con la convenzione di prefisso sei-lettere-maiuscole-più-+	bool	—	Ancorato all’inizio del nome
FontDesubsetter::extractSubsetPrefix()	string $baseFontName	Restituisce il tag di subset di sei lettere	string	—	Stringa vuota per i nomi non-subset
FontDesubsetter::generateDesubsetPlan()	list<SubsetInfo> $subsets	Raccoglie le voci il cui isSubset è true e somma la stima di dimensione	DesubsetPlan	Non solleva eccezioni	Le voci non-subset vengono ignorate silenziosamente
SubsetInfo	costruttore: $fontName, $baseFont, $subsetGlyphCount, $fullGlyphCount, $isSubset, $encoding	Descrizione immutabile di una voce /BaseFont	—	InvalidArgumentException su un conteggio di glifi negativo, o un conteggio di subset superiore al conteggio completo	final readonly; tutte le proprietà pubbliche
SubsetInfo::subsetPrefix()	nessuno	Estrae il tag di sei lettere da fontName	string	—	Stringa vuota quando non è un subset o il + non si trova alla posizione sei
SubsetInfo::coveragePercent()	nessuno	Quota del subset rispetto all’insieme completo di glifi	float in [0.0, 100.0]	—	Restituisce 0.0 quando fullGlyphCount è 0
DesubsetPlan	costruttore: list<SubsetInfo> $targets, int $estimatedSizeIncrease	Piano di de-subsetting immutabile	—	—	final readonly; tutte le proprietà pubbliche
DesubsetPlan::count()	nessuno	Numero di font mirati	int	—	Pari alla lunghezza di targets
DesubsetPlan::totalGlyphsNeeded()	nessuno	Glifi mancanti sommati su tutti i target	int	—	Somma di fullGlyphCount - subsetGlyphCount per target

Firme dei punti di ingresso

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

Contratto di comportamento

Scansione e rilevamento dei subset

analyzeSubsets() estrae i token del nome /BaseFont dai byte grezzi con una corrispondenza di pattern a livello di byte. I nomi duplicati collassano in un’unica voce; l’ordine segue la prima comparsa. Ogni nome distinto produce un SubsetInfo, che sia o meno un subset. Un nome è un subset quando inizia con esattamente sei lettere ASCII maiuscole seguite da +, la convenzione di §9.9.2. Per i nomi di subset, baseFont è il nome con il prefisso di sette caratteri rimosso. Per i nomi ordinari, baseFont è uguale a fontName. Ogni nome di subset distinto viene riportato come voce a sé, in linea con l’indicazione di §9.9.2 di trattare i subset come entità indipendenti.

Rilevamento della codifica

Per ciascun font, lo scanner esamina una finestra di byte delimitata dopo l’occorrenza di /BaseFont. Una voce di nome /Encoding all’interno della finestra prevale. In mancanza, viene riportata una sottostringa Identity-H o Identity-V presente nella finestra. Fallendo entrambe, la voce riporta Unknown. I valori di codifica contenuti in dizionari o raggiunti tramite riferimenti indiretti riportano Unknown.

Conteggio dei glifi

Entrambi i conteggi dei glifi sono stime. subsetGlyphCount deriva dagli array di larghezze visibili in prossimità della voce del font: un array /W di un CIDFont produce all’incirca un glifo per ogni tripletta di larghezza, e un array /Widths di un font semplice produce un glifo per ogni voce numerica. Quando nessuno dei due array è visibile nella finestra, si applica un piccolo valore predefinito fisso. Quando l’occorrenza di /BaseFont non può essere rilocalizzata per la ricerca nella finestra, il conteggio è 0. fullGlyphCount deriva da euristiche sui nomi di famiglia: una tabella di famiglie latine ben note, un insieme di indicatori di nomi di famiglia CJK e un valore minimo generico in caso contrario. Il programma font incorporato non viene mai analizzato. Le specifiche tabelle, le dimensioni delle finestre e le costanti sono dettagli implementativi, non sono pubblicati e possono cambiare tra una release e l’altra.

Generazione del piano

generateDesubsetPlan() filtra l’input alle voci il cui isSubset è true. Ogni target contribuisce con il proprio conteggio di glifi mancanti, moltiplicato per una costante fissa di byte medi per glifo, a estimatedSizeIncrease. Il piano è una proiezione per decisioni di capacità, non un delta misurato. L’esecuzione di un piano — la riscrittura dei programmi font — è al di fuori di questo modulo.

Determinismo

L’intera superficie è una funzione pura del proprio input. Byte identici producono risultati identici. Non c’è casualità, né chiamate di rete, né accesso al filesystem.

Casi limite e modalità di errore

• La costruzione di SubsetInfo rifiuta gli stati non validi: un conteggio di glifi negativo, o un conteggio di subset superiore al conteggio completo, solleva InvalidArgumentException.
• analyzeSubsets() può propagare quell’eccezione in un caso limite: un font il cui nome corrisponde a una famiglia nota ma il cui array di larghezze visibile produce una stima del subset più grande del valore di conteggio completo della famiglia.
• Il rilevamento opera sulla rappresentazione in byte. Le voci /BaseFont serializzate all’interno di object stream compressi sono invisibili; decomprimere tali stream prima della scansione.
• Le voci il cui chiave e valore /BaseFont sono separati da spazi bianchi diversi da un singolo spazio vengono comunque rilevate, ma la ricerca nella finestra per singolo font non riesce a rilocalizzarle. Tali voci riportano codifica Unknown e un conteggio di glifi del subset di 0.
• I nomi PDF che usano byte con escape # vengono riportati in forma grezza con escape; gli escape non vengono decodificati.
• I nomi /BaseFont duplicati collassano in un’unica voce. Due oggetti font distinti che condividono un nome sono indistinguibili per questo scanner.
• generateDesubsetPlan() non fallisce mai su input non-subset; le voci con isSubset impostato a false vengono semplicemente escluse da targets.
• Tutti i conteggi e estimatedSizeIncrease sono euristiche. Non trattarli come valori misurati; usarli solo per il triage e la pianificazione della capacità.
• In questo modulo non avviene alcuna operazione crittografica, quindi non esiste un comportamento specifico della modalità FIPS.

Conformità

Affermazione	Standard	Clausola
Il rilevamento dei subset corrisponde alla convenzione di denominazione dei subset: un tag di sei lettere maiuscole seguite da + anteposto al valore BaseFont.	ISO 32000-2:2020	§9.9.2
Ogni nome di subset distinto viene riportato in modo indipendente, seguendo la raccomandazione di trattare i subset multipli come entità separate.	ISO 32000-2:2020	§9.9.2

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. Si tratta di dichiarazioni di capacità, non di certificazioni. NextPDF non detiene alcuna certificazione e non ne concede alcuna. Il modulo afferma il rilevamento della convenzione di denominazione e la reportistica deterministica; non afferma l’accuratezza delle stime del conteggio dei glifi o della dimensione.

Note di sviluppo

• Installare con composer require nextpdf/pro:^3. Disponibile da nextpdf/pro 1.9.0; attuale in nextpdf/pro 3.1.0.
• FontDesubsetter è senza stato. Costruirlo una sola volta e riutilizzarlo tra documenti e flussi di lavoro.
• Fornire ad analyzeSubsets() byte decompressi quando la copertura dei subset è rilevante; i dizionari font impacchettati in object stream vengono altrimenti mancati.
• Ramificare su SubsetInfo::isSubset prima di agire; l’elenco dei risultati include intenzionalmente i font non-subset a scopo di inventario.
• Usare DesubsetPlan::totalGlyphsNeeded() e estimatedSizeIncrease per decidere se il de-subsetting valga il costo in dimensione del file prima di procurarsi i programmi font completi.
• La scansione è lineare rispetto alla lunghezza dell’input con ricerche nella finestra per singolo font delimitate. Il modulo non memorizza nulla e non emette telemetria.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Font Tools (capability) — installazione, avvio rapido ed esempi di flusso di lavoro di pianificazione.
• Optimizer — Riferimento approfondito — la superficie affine di riduzione delle dimensioni, inclusa l’ottimizzazione relativa ai font.
• Core font module — incorporamento e subsetting dei font durante la creazione dei documenti in NextPDF Core.