Font Tools — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona stanowi referencję na poziomie kontraktu dla NextPDF Pro Font Tools. Powierzchnię tworzą jeden skaner, NextPDF\Pro\FontTools\FontDesubsetter, oraz dwa niezmienne obiekty wartości, SubsetInfo i DesubsetPlan. Skaner odczytuje surowe bajty PDF, zgłasza każdy odrębny wpis /BaseFont i oznacza wpisy zgodne z konwencją nazewnictwa podzbiorów według ISO 32000-2:2020 §9.9.2. Plan agreguje oznaczone podzbiory i szacuje koszt w bajtach odtworzenia pełnych programów czcionek. Moduł wyłącznie analizuje i szacuje; nigdy nie przepisuje osadzonego programu czcionki. Ta strona opisuje publiczne API, kontrakt obserwowalnego zachowania oraz tryby awarii.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się przy użyciu koperty licencyjnej poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga licencji dla pojedynczej funkcji nie ogranicza dostępu do tego modułu. Klasy Font Tools są dostępne zawsze, gdy zainstalowano nextpdf/pro.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
FontDesubsetter	brak	Bezstanowy skaner surowych bajtów PDF	—	—	final; bezpieczny do ponownego użycia w wielu dokumentach
FontDesubsetter::analyzeSubsets()	string $pdfData	Zgłasza każdy odrębny wpis /BaseFont, podzbiór lub nie, oznaczony przez isSubset	list<SubsetInfo>	InvalidArgumentException, gdy szacunek podzbioru wyprowadzony z szerokości przekracza szacunek pełnej liczby wyprowadzony z nazwy	Skan na poziomie bajtów; skompresowane strumienie obiektów nie są dekodowane
FontDesubsetter::isSubsetFont()	string $baseFontName	Dopasowuje konwencję prefiksu sześciu wielkich liter zakończonego znakiem +	bool	—	Zakotwiczone na początku nazwy
FontDesubsetter::extractSubsetPrefix()	string $baseFontName	Zwraca sześcioliterowy znacznik podzbioru	string	—	Pusty ciąg dla nazw niebędących podzbiorami
FontDesubsetter::generateDesubsetPlan()	list<SubsetInfo> $subsets	Zbiera wpisy, których isSubset ma wartość true, i sumuje szacunek rozmiaru	DesubsetPlan	Nie zgłasza wyjątku	Wpisy niebędące podzbiorami są pomijane po cichu
SubsetInfo	konstruktor: $fontName, $baseFont, $subsetGlyphCount, $fullGlyphCount, $isSubset, $encoding	Niezmienny opis jednego wpisu /BaseFont	—	InvalidArgumentException przy ujemnej liczbie glifów lub liczbie glifów podzbioru przekraczającej liczbę pełną	final readonly; wszystkie właściwości publiczne
SubsetInfo::subsetPrefix()	brak	Wyodrębnia sześcioliterowy znacznik z fontName	string	—	Pusty ciąg, gdy nie jest podzbiorem lub znak + nie znajduje się na szóstej pozycji
SubsetInfo::coveragePercent()	brak	Udział podzbioru w pełnym zestawie glifów	float w [0.0, 100.0]	—	Zwraca 0.0, gdy fullGlyphCount wynosi 0
DesubsetPlan	konstruktor: list<SubsetInfo> $targets, int $estimatedSizeIncrease	Niezmienny plan odtwarzania podzbiorów	—	—	final readonly; wszystkie właściwości publiczne
DesubsetPlan::count()	brak	Liczba docelowych czcionek	int	—	Równa długości targets
DesubsetPlan::totalGlyphsNeeded()	brak	Brakujące glify zsumowane dla wszystkich celów	int	—	Suma fullGlyphCount - subsetGlyphCount dla każdego celu

Sygnatury punktów wejścia

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

Kontrakt zachowania

Skanowanie i wykrywanie podzbiorów

analyzeSubsets() wyodrębnia tokeny nazw /BaseFont z surowych bajtów za pomocą dopasowania wzorca na poziomie bajtów. Zduplikowane nazwy zwijają się do jednego wpisu; kolejność wynika z pierwszego wystąpienia. Każda odrębna nazwa daje jeden SubsetInfo, niezależnie od tego, czy jest podzbiorem. Nazwa jest podzbiorem, gdy zaczyna się od dokładnie sześciu wielkich liter ASCII zakończonych znakiem + — konwencja z §9.9.2. Dla nazw podzbiorów baseFont to nazwa z usuniętym siedmioznakowym prefiksem. Dla nazw zwykłych baseFont jest równe fontName. Każda odrębna nazwa podzbioru jest zgłaszana jako osobny wpis, zgodnie z zaleceniem §9.9.2, aby traktować podzbiory jako niezależne jednostki.

Wykrywanie kodowania

Dla każdej czcionki skaner przeszukuje ograniczone okno bajtów po wystąpieniu /BaseFont. Wpis nazwy /Encoding w oknie ma pierwszeństwo. W razie jego braku zgłaszany jest podciąg Identity-H lub Identity-V z okna. Gdy nie ma żadnego z nich, wpis zgłasza Unknown. Wartości kodowania przechowywane w słownikach lub osiągane przez odwołania pośrednie zgłaszają Unknown.

Rozliczanie glifów

Obie liczby glifów są szacunkami. subsetGlyphCount wyprowadza się z tablic szerokości widocznych w pobliżu wpisu czcionki: tablica /W czcionki CIDFont daje mniej więcej jeden glif na trójkę szerokości, a tablica /Widths czcionki prostej daje jeden glif na wpis liczbowy. Gdy żadna z tablic nie jest widoczna w oknie, stosuje się niewielką stałą wartość domyślną. Gdy wystąpienia /BaseFont nie można ponownie zlokalizować na potrzeby przeszukiwania okna, liczba wynosi 0. fullGlyphCount wyprowadza się z heurystyk nazw rodzin: tablicy znanych rodzin łacińskich, zestawu wskaźników nazw rodzin CJK oraz ogólnego progu w pozostałych przypadkach. Osadzony program czcionki nigdy nie jest parsowany. Konkretne tablice, rozmiary okien i stałe są szczegółem implementacyjnym, nie są publikowane i mogą się zmieniać między wydaniami.

Generowanie planu

generateDesubsetPlan() filtruje dane wejściowe do wpisów, których isSubset ma wartość true. Każdy cel wnosi swoją liczbę brakujących glifów, pomnożoną przez stałą średnią liczbę bajtów na glif, do estimatedSizeIncrease. Plan jest prognozą na potrzeby decyzji o pojemności, a nie zmierzoną różnicą. Wykonanie planu — przepisanie programów czcionek — jest poza tym modułem.

Determinizm

Cała powierzchnia jest czystą funkcją swoich danych wejściowych. Identyczne bajty dają identyczne wyniki. Nie ma losowości, wywołań sieciowych ani dostępu do systemu plików.

Przypadki brzegowe i tryby awarii

• Konstrukcja SubsetInfo odrzuca nieprawidłowe stany: ujemna liczba glifów lub liczba glifów podzbioru przekraczająca liczbę pełną zgłasza InvalidArgumentException.
• analyzeSubsets() może propagować ten wyjątek w jednym skrajnym przypadku: czcionka, której nazwa pasuje do znanej rodziny, ale której widoczna tablica szerokości daje większy szacunek podzbioru niż wartość pełnej liczby dla tej rodziny.
• Wykrywanie działa na reprezentacji bajtowej. Wpisy /BaseFont serializowane wewnątrz skompresowanych strumieni obiektów są niewidoczne; przed skanowaniem zdekompresuj te strumienie.
• Wpisy, w których klucz i wartość /BaseFont są oddzielone znakiem białym innym niż pojedyncza spacja, są nadal wykrywane, ale przeszukiwanie okna dla danej czcionki nie potrafi ich ponownie zlokalizować. Takie wpisy zgłaszają kodowanie Unknown i liczbę glifów podzbioru 0.
• Nazwy PDF używające bajtów z sekwencjami ucieczki # są zgłaszane w surowej postaci z sekwencjami ucieczki; sekwencje nie są dekodowane.
• Zduplikowane nazwy /BaseFont zwijają się do jednego wpisu. Dwa odrębne obiekty czcionek o wspólnej nazwie są nierozróżnialne dla tego skanera.
• generateDesubsetPlan() nigdy nie zawodzi przy danych niebędących podzbiorami; wpisy z isSubset ustawionym na false są po prostu wykluczane z targets.
• Wszystkie liczby oraz estimatedSizeIncrease są heurystykami. Nie traktuj ich jako wartości zmierzonych; używaj ich wyłącznie do triażu i planowania pojemności.
• W tym module nie zachodzi żadna operacja kryptograficzna, więc nie ma zachowania specyficznego dla trybu FIPS.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Wykrywanie podzbiorów odpowiada konwencji nazewnictwa podzbiorów: znacznik sześciu wielkich liter zakończony znakiem + poprzedzający wartość BaseFont.	ISO 32000-2:2020	§9.9.2
Każda odrębna nazwa podzbioru jest zgłaszana niezależnie, zgodnie z zaleceniem traktowania wielu podzbiorów jako osobnych jednostek.	ISO 32000-2:2020	§9.9.2

Wszystkie klauzule są parafrazowane; NextPDF nie odtwarza tekstu normatywnego. Są to deklaracje możliwości, a nie certyfikaty. NextPDF nie posiada żadnego certyfikatu i żadnego nie udziela. Moduł deklaruje wykrywanie konwencji nazewnictwa oraz deterministyczne raportowanie; nie deklaruje dokładności szacunków liczby glifów ani rozmiaru.

Uwagi programistyczne

• Zainstaluj poleceniem composer require nextpdf/pro:^3. Dostępne od nextpdf/pro 1.9.0; aktualne w nextpdf/pro 3.1.0.
• FontDesubsetter jest bezstanowy. Utwórz go raz i używaj ponownie w wielu dokumentach i wątkach pracy.
• Podawaj analyzeSubsets() zdekompresowane bajty, gdy pokrycie podzbioru ma znaczenie; w przeciwnym razie słowniki czcionek upakowane w strumieniach obiektów zostaną pominięte.
• Rozgałęziaj na podstawie SubsetInfo::isSubset przed podjęciem działania; lista wyników celowo zawiera czcionki niebędące podzbiorami na potrzeby inwentaryzacji.
• Użyj DesubsetPlan::totalGlyphsNeeded() oraz estimatedSizeIncrease, aby zdecydować, czy odtwarzanie podzbiorów jest warte kosztu rozmiaru pliku, zanim pozyskasz pełne programy czcionek.
• Skanowanie jest liniowe względem długości danych wejściowych z ograniczonymi przeszukiwaniami okna dla każdej czcionki. Moduł niczego nie przechowuje i nie emituje żadnej telemetrii.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tablice mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Font Tools (funkcja) — instalacja, szybki start i przykłady przepływu planowania.
• Optimizer — szczegółowa dokumentacja referencyjna — siostrzana powierzchnia redukcji rozmiaru, w tym optymalizacja związana z czcionkami.
• Moduł czcionek Core — osadzanie i tworzenie podzbiorów czcionek podczas tworzenia dokumentu w NextPDF Core.