From 8814984f531e500afd21828146bdf0046a072fa4 Mon Sep 17 00:00:00 2001 From: Dan Krieger Date: Mon, 2 Nov 2026 15:50:40 -0800 Subject: [PATCH 1/2] fix(font): keep numeric words' glyphs when the decode cache evicts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PdfFont::decodeUtf8 caches glyphs by text, evicting the oldest entry with array_shift once 2048 are held. PHP stores a key like "1" as the integer 1, and array_shift renumbers integer keys, so after the first eviction a numeric word could be served another one's glyphs: "1" came back as "15", "21" or "42". With an embedded font, a document of more than ~2048 distinct words printed wrong numbers from then on — a 100-page invoice showed 2,900 of its 5,000 quantities wrong, and line breaks were measured with the wrong widths. Eviction now unsets the first key, which leaves the others alone. Co-Authored-By: Claude Opus 5.5 --- src/Pdf/PdfFont.php | 2 +- tests/Pdf/PdfFontDecodeCacheTest.php | 68 ++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 tests/Pdf/PdfFontDecodeCacheTest.php diff --git a/src/Pdf/PdfFont.php b/src/Pdf/PdfFont.php index 9d570dc..99f63a5 100644 --- a/src/Pdf/PdfFont.php +++ b/src/Pdf/PdfFont.php @@ -472,7 +472,7 @@ public function decodeUtf8(string $utf8): array // Bounded FIFO eviction: drop oldest entry when reached cap. if (count($this->decodeCache) >= self::DECODE_CACHE_MAX) { - array_shift($this->decodeCache); + unset($this->decodeCache[array_key_first($this->decodeCache)]); } $this->decodeCache[$utf8] = $out; diff --git a/tests/Pdf/PdfFontDecodeCacheTest.php b/tests/Pdf/PdfFontDecodeCacheTest.php new file mode 100644 index 0000000..1a01fe9 --- /dev/null +++ b/tests/Pdf/PdfFontDecodeCacheTest.php @@ -0,0 +1,68 @@ +font = new PdfFont(TtfFile::fromFile($path)); + } + + #[Test] + public function numeric_words_keep_their_glyphs_after_the_cache_evicts(): void + { + $expected = []; + foreach (['1', '15', '21', '42'] as $word) { + $expected[$word] = $this->font->decodeUtf8($word); + } + // Fill the cache past its cap so the oldest entries are evicted. + for ($i = 0; $i < self::CACHE_MAX + 10; $i++) { + $this->font->decodeUtf8("w$i"); + $this->font->decodeUtf8((string) (1000 + $i)); + } + + foreach ($expected as $word => $glyphs) { + // Array keys come back as ints too: "1" is 1. + self::assertSame($glyphs, $this->font->decodeUtf8((string) $word), "glyphs of \"$word\""); + } + } + + #[Test] + public function a_numeric_word_still_cached_is_not_confused_with_another(): void + { + // "1" and "15" stay in the cache while a string key ahead of them + // is evicted — the case that renumbered "15" to key 1. + $this->font->decodeUtf8('first'); + $one = $this->font->decodeUtf8('1'); + $this->font->decodeUtf8('15'); + for ($i = 0; $i < self::CACHE_MAX - 2; $i++) { + $this->font->decodeUtf8("w$i"); + } + + self::assertCount(1, $one); + self::assertSame($one, $this->font->decodeUtf8('1')); + self::assertCount(2, $this->font->decodeUtf8('15')); + } +} From f50b16ab39db155b7cab7673362b1bc65164fe00 Mon Sep 17 00:00:00 2001 From: Dan Krieger Date: Tue, 3 Nov 2026 14:55:16 -0800 Subject: [PATCH 2/2] perf(font): keep long strings out of the large decode cache decodeUtf8 held up to 2,048 results per font whatever their length, and each costs ~400 bytes per character. When whole lines are drawn as one run, the cache fills with strings that rarely come back: an outside caller drawing 6,900 runs held 37 MB of its 38 MB there. Strings up to 32 bytes - words, numbers, labels - keep the large cache. Longer ones go in a cache of the 16 most recent, which catches the repeat decodes of a run while it is drawn (shaped, then encoded). Replaying every lookup from a prose document and a 100-page invoice, the miss rate is unchanged (8.9% -> 8.7%, 2.6% -> 2.6%); a flat cap of 8 would have raised it to 54% and 22%. Prose peak memory goes from 23.4 MB to 13.3 MB at the same speed; output is byte-identical. Co-Authored-By: Claude Opus 5.5 --- src/Pdf/PdfFont.php | 50 +++++++++++++++----- tests/Pdf/PdfFontDecodeCacheTest.php | 71 ++++++++++++++++++++++++++-- 2 files changed, 104 insertions(+), 17 deletions(-) diff --git a/src/Pdf/PdfFont.php b/src/Pdf/PdfFont.php index 99f63a5..9081cb5 100644 --- a/src/Pdf/PdfFont.php +++ b/src/Pdf/PdfFont.php @@ -130,6 +130,7 @@ public function reset(): void $this->usedGlyphs = []; $this->writerRegistrations = new \WeakMap; $this->decodeCache = []; + $this->recentDecodes = []; } /** @@ -372,16 +373,31 @@ public function supportsText(string $text): bool private bool $indicShapingEnabled = true; /** - * Bounded LRU cache for decodeUtf8 results - TextMeasurer - * (Engine layout) repeatedly calls on the same words while measuring - * line-fits, justification, etc. + * decodeUtf8 results for short strings - words, numbers, labels - which + * come back throughout a document: layout measures the same words over + * and over. Oldest out first once DECODE_CACHE_MAX are held. * * @var array> */ private array $decodeCache = []; + /** + * decodeUtf8 results for longer strings, such as a whole line drawn at + * once. These mostly come back within the same draw (shaped, then + * encoded), so a few recent ones are enough. Each entry costs ~400 + * bytes per character, so they stay out of the large cache. + * + * @var array> + */ + private array $recentDecodes = []; + private const DECODE_CACHE_MAX = 2048; + private const RECENT_DECODES_MAX = 16; + + /** Strings up to this many bytes go in the large cache. */ + private const SHORT_STRING_MAX_BYTES = 32; + /** * Disable Arabic shaping (for debug or if font handles * shaping itself via GSUB rather than Presentation Forms B). @@ -423,12 +439,12 @@ public function disableIndicShaping(): void */ public function decodeUtf8(string $utf8): array { - // Memo cache. TextMeasurer repeatedly calls decodeUtf8 - // on the same words during layout passes; without cache the pipeline - // (utf8 to cps + Arabic/Indic shape + Bidi + cmap + rphf) runs - // every time and blows memory. Bounded FIFO cap = 2048 entries. - if (isset($this->decodeCache[$utf8])) { - return $this->decodeCache[$utf8]; + // The pipeline below (utf8 to cps + Arabic/Indic shape + Bidi + + // cmap + rphf) is cached; see $decodeCache and $recentDecodes. + $short = strlen($utf8) <= self::SHORT_STRING_MAX_BYTES; + $cached = $short ? ($this->decodeCache[$utf8] ?? null) : ($this->recentDecodes[$utf8] ?? null); + if ($cached !== null) { + return $cached; } $cps = self::utf8ToCps($utf8); @@ -470,11 +486,19 @@ public function decodeUtf8(string $utf8): array } } - // Bounded FIFO eviction: drop oldest entry when reached cap. - if (count($this->decodeCache) >= self::DECODE_CACHE_MAX) { - unset($this->decodeCache[array_key_first($this->decodeCache)]); + // Drop the oldest entry at the cap. unset, not array_shift: a key + // like "1" is stored as an integer, and array_shift would renumber it. + if ($short) { + if (count($this->decodeCache) >= self::DECODE_CACHE_MAX) { + unset($this->decodeCache[array_key_first($this->decodeCache)]); + } + $this->decodeCache[$utf8] = $out; + } else { + if (count($this->recentDecodes) >= self::RECENT_DECODES_MAX) { + unset($this->recentDecodes[array_key_first($this->recentDecodes)]); + } + $this->recentDecodes[$utf8] = $out; } - $this->decodeCache[$utf8] = $out; return $out; } diff --git a/tests/Pdf/PdfFontDecodeCacheTest.php b/tests/Pdf/PdfFontDecodeCacheTest.php index 1a01fe9..d3de3df 100644 --- a/tests/Pdf/PdfFontDecodeCacheTest.php +++ b/tests/Pdf/PdfFontDecodeCacheTest.php @@ -10,10 +10,13 @@ use PHPUnit\Framework\TestCase; /** - * decodeUtf8 caches glyphs by text. PHP stores a key like "1" as the - * integer 1, and evicting with array_shift renumbered every integer key: - * once the cache was full, "1" could come back as the glyphs of "15". A - * long invoice printed its quantities as 42, 51, 21… from page 43 on. + * decodeUtf8 caches glyphs by text: short strings in a large cache, longer + * ones in a small cache of recent strings. + * + * PHP stores a key like "1" as the integer 1, and evicting with array_shift + * renumbered every integer key: once the cache was full, "1" could come + * back as the glyphs of "15". A long invoice printed its quantities as 42, + * 51, 21… from page 43 on. */ final class PdfFontDecodeCacheTest extends TestCase { @@ -65,4 +68,64 @@ public function a_numeric_word_still_cached_is_not_confused_with_another(): void self::assertSame($one, $this->font->decodeUtf8('1')); self::assertCount(2, $this->font->decodeUtf8('15')); } + + #[Test] + public function long_lines_stay_out_of_the_word_cache(): void + { + $word = $this->font->decodeUtf8('invoice'); + for ($i = 0; $i < self::CACHE_MAX + 10; $i++) { + $this->font->decodeUtf8("Line $i of a paragraph drawn as one run of text."); + } + + self::assertSame(['invoice'], array_keys($this->cache('decodeCache'))); + self::assertCount(16, $this->cache('recentDecodes')); + self::assertSame($word, $this->font->decodeUtf8('invoice')); + } + + #[Test] + public function a_line_decoded_again_soon_is_served_from_the_cache(): void + { + $line = 'A line of text drawn once to shape it, then again to encode it.'; + $glyphs = $this->font->decodeUtf8($line); + for ($i = 0; $i < 15; $i++) { + $this->font->decodeUtf8("Another line of text, number $i of fifteen."); + } + + self::assertArrayHasKey($line, $this->cache('recentDecodes')); + self::assertSame($glyphs, $this->font->decodeUtf8($line)); + } + + #[Test] + public function cached_glyphs_match_a_fresh_decode_on_either_side_of_the_cutoff(): void + { + $path = __DIR__.'/../../.cache/fonts/liberation-fonts-ttf-2.1.5/LiberationSans-Regular.ttf'; + $strings = [str_repeat('a', 32), str_repeat('b', 33), str_repeat('é', 16), str_repeat('é', 17)]; + foreach ($strings as $s) { + $this->font->decodeUtf8($s); + } + + foreach ($strings as $s) { + $fresh = new PdfFont(TtfFile::fromFile($path)); + self::assertSame($fresh->decodeUtf8($s), $this->font->decodeUtf8($s), $s); + } + self::assertCount(2, $this->cache('decodeCache')); + self::assertCount(2, $this->cache('recentDecodes')); + } + + #[Test] + public function reset_empties_both_caches(): void + { + $this->font->decodeUtf8('word'); + $this->font->decodeUtf8('A line long enough to skip the word cache entirely.'); + $this->font->reset(); + + self::assertSame([], $this->cache('decodeCache')); + self::assertSame([], $this->cache('recentDecodes')); + } + + /** @return array */ + private function cache(string $name): array + { + return (new \ReflectionProperty(PdfFont::class, $name))->getValue($this->font); + } }