Move Otl's three non-shaping tenants out: OtlData, OtlTags and the debugOTL trace (#160)

[jakejackson1]

Part of #160: the sixth Order checkbox, "Otl's three non-shaping tenants (5)". This moves all three out of Otl. Once it merges, the checkbox can be ticked.

It's one PR with one commit per tenant, and each commit can be reviewed on its own. They share no code, and all three are pure refactors: no fixture moves.

Base. refactor/160-otldump-gsub-array (#190). #177 and #178 were squash-merged into gravitypdf, and the stack below this PR was rebased onto it. This branch was then rebased with --onto from the old #190 head (d820375) to the new one (e5db3e5). #186, #188 and #190 are still open, so the base stays #190.

1. Script and language tags → Shaper\OtlTags

_getOTLscriptTag and _getOTLLangTag were private lookup tables. They're now OtlTags::script() and OtlTags::language(), and Otl::selectScriptAndLanguage() is their only caller.

• The Indic switch is now a v2 tag → original tag table.
• The useOTL gate is now a method that returns the group's bit.
• script() drops $mode, which the old method never read.

Exact results. Before deleting the old private methods, I compared them with the new ones through reflection:

• Script: 107,016,000 cases. Every Ucdn script block with its own tag and five others × 4 shapers × 8 useOTL masks × 3,000+ offered-script sets.
• Language: 517,720 cases. Every Ucdn language, alone and with region and script subtags, against every OpenType language tag.
• None differed.

Two existing defects are kept exactly and filed separately, not fixed here:

• An Indic run the font has no tag for is laid out with another Indic script's original tag #192: a v2 Indic tag falls through to the original tags of every script listed after it (bng2 in a font with only deva → deva). OtlTagsTest pins this, so a fix will change that test.
• A Chinese region never selects its OpenType language system: ZHH, ZHS and ZHT are unreachable #191: the language-and-region lookup can never match, because Ucdn::$ot_languages keys regions as zh-hk and the code looks up zhhk. ZHH, ZHS and ZHT are unreachable.

2. Debug trace → OtlDump::shapingStep()

_dumpproc isn't dead code. Otl::$debugOTL is a public var, off by default, and $mpdf->otl is public, so a caller can switch the trace on. Nothing in src/, tests/ or utils/ does. The trace ends the run with exit.

It's now a static on OtlDump that returns the HTML, placed beside the other report* methods. The 28 call sites echo OtlDump::shapingStep($this->OTLdata, …).

• Being static, Otl never builds a dump.
• OtlDump (and TTFontFile under it) only loads once the trace is on.
• Nothing about the shaper's normal path changes.

Exact output. Five outputs were captured from _dumpproc before it was deleted, and the four unit tests expect four of them. The whole trace of a two-Beh run is byte-identical before and after. Because of the exit, the end-to-end test (ShapingTraceTest::testTheShaperTracesTheRunFromBeginningToEnd) runs the shaper in a child process (tests/Mpdf/Fixtures/shaping-trace.php).

3. OTLdata buffer operations → Shaper\OtlData

old Otl method	new
splitOTLdata	OtlData::split
sliceOTLdata	OtlData::slice
prependOTLchar	OtlData::prependChar
removeChar	OtlData::removeChar(…, $encoding)
replaceSpace	OtlData::nbspToSpace(…, $encoding)
trimOTLdata	OtlData::trim

All callers in src/ now call OtlData directly: Mpdf (28 calls), Bidi (9), Tag\BlockTag and Tag\Br.

Why static functions over the same arrays, not a value object. I checked StateSnapshot first, and it settles the question:

• Runs are copied by assignment throughout Mpdf ($savedPreOTLdata, $objattr['OTLdata'], textbuffer[..][18]), and each copy is expected to be independent.
• textbuffer and OTLdata are exactly what Mpdf::getStateSnapshot() captures for the table-of-contents look-ahead. StateSnapshot copies arrays by value but shares any object inside them.
• So a run object trimmed or split during a look-ahead would stay changed after restoreStateSnapshot().
• A real object would need a clone at every one of those copies, across hundreds of lines of Mpdf. That's a different and riskier change than this checkbox.

Encoding. removeChar and replaceSpace read Mpdf::$mb_enc through Otl's $mpdf, so the static versions take the encoding as an argument.

• Bidi::prepare() took an Otl only for removeChar. It now takes the encoding instead: Bidi is fork-only, and Mpdf is its only caller.
• Mpdf no longer creates an Otl just before calling it. ServiceFactory always sets $otl, so that guard never fired.

BC. All six stay on Otl as one-line @deprecated delegates, the way #167 kept unicode_hex(). Otl is reachable through the public Mpdf::$otl, and upstream mpdf/mpdf exposes splitOTLdata, sliceOTLdata, removeChar, replaceSpace and trimOTLdata as public. prependOTLchar is fork-only (#145) but was public here too.

Exact results. Before the old methods were replaced, 200,000 random runs and operations were compared between old and new. The inputs covered empty, null and false runs, missing parts, out-of-order GPOSinfo, four-byte characters, both encodings, and cut points at 0, at the end and past the end. Return values, by-reference changes, warnings and exceptions were all identical.

Tests

• tests/Mpdf/Shaper/OtlDataTest.php (25 tests, all on hand-built OTLdata arrays): cut at 0, at the end and between cut and restart; restart '' and 0; GPOSinfo ordering; removal at either end, and positions counted in characters with a four-byte emoji ahead; a no-break space the run no longer holds as U+00A0; U+3000 trimming; one-sided trims; all spaces; null and char_data => null; slice/prependChar of []. A group cut down to nothing is compared as a string, because substr() past the end returns false on PHP 5.6.
• tests/Mpdf/Shaper/OtlTagsTest.php (32 tests): each useOTL group including both CJK ends and Hangul; v2 vs original Indic tags, with and without a shaper; the An Indic run the font has no tag for is laid out with another Indic script's original tag #192 fall-through; DFLT → dflt → latn; language with region, script, script+region, upper case, unknown language, missing DFLT, empty tag, empty offer.
• tests/Mpdf/ShapingTraceTest.php (5 tests), described above.
• OtlTest: the six deprecated delegates return what OtlData returns.
• BidiTest: Bidi::prepare() removes RLE/PDF from the text and its run, and sets their levels.

Mutation check

47 mutants: 24 in OtlData, 16 in OtlTags, 5 in shapingStep, 1 in Otl's trace wiring and 1 in a delegate. Each was run against the full suite, snapshots included.

Caught by a unit test only:

• split: restart 0 no longer read as none; first part cut at the restart; no ksort of either part.
• slice: < → <= at the end; no ksort.
• prependChar: no defaults for []; GPOSinfo not shifted.
• removeChar: GPOSinfo of the removed character kept; > → >=.
• nbspToSpace: uni set without checking it's 160.
• trim: U+3000 ignored at either end; >= → > for either end.
• OtlTags: every group bit and range end; original tags tried without a shaper; DFLT/dflt order; language not lower-cased; the DFLT-only fallback made unconditional.
• shapingStep: all 5 mutants, plus the Otl wiring and the delegate mutants.

Also caught by snapshots and golden masters:

mutant	also caught by
split >= → > at the restart	AutoFontSnapshotTest
removeChar counting bytes / ignoring its encoding	DictionaryLineBreakingSnapshotTest, AutoFontSnapshotTest, BidiTest
nbspToSpace counting bytes	RtlSnapshotTest, IndexOfFiftyEntriesSnapshotTest, LongTableOfContentsSnapshotTest
trim left/right flags swapped	RtlSnapshotTest, AutoFontSnapshotTest, ZeroFontSizeSnapshotTest
trim without its is_array guard	Issue905Test, JustifySnapshotTest, RtlSnapshotTest
useOTL gate removed	11 shaping golden masters
latn fallback removed	TaiThamSakotSnapshotTest, SeaTest, Carlito golden master
#192 fixed	NotoSansGurmukhiUI shaping golden master
whole-list fall-through; original tag reported as v2; no DFLT language fallback	AutoFontSnapshotTest

Survivors, all equivalent or unreachable:

• slice group read with a suppressed warning instead of isset: the same '' for [].
• language() without its empty-offer early return: strpos('', …) gives the same ''.
• The two region-parsing mutants in language(): the only branch that reads the region can't match (A Chinese region never selects its OpenType language system: ZHH, ZHS and ZHT are unreachable #191).

/simplify follow-up

The last commit applies what four review agents found:

• OtlTags::script() now walks the tag table once instead of calling array_search and then array_slice. Over 53,508,000 cases it gives the same result as the committed version.
• BidiTest::sort() now reuses chunk(), and its docblock is back in the right place.
• Three comments that restated code or said something wrong were dropped.

Suggestions not taken:

• A private Otl wrapper around the 28 trace call sites. It's optional, and the call sites were already this shape.
• A fixed temp dir for the trace subprocess. The font cache is keyed by family name and only rewritten when the file size changes, so a stale cache could survive between runs.
• Dropping Tag::$otl. Tag\Columns still passes it on, and removing it changes the constructor signature.

Verification (after the rebase onto e5db3e5, re-run after the /simplify commit)

• Full suite: 2053 tests, 5904 assertions, 1 skipped. That's 64 new tests on top of the base.
• Snapshots: 79 tests, 110 assertions. Imagick and Ghostscript are present, and no byte-difference notes were printed. Line-breaking, bidi, hyphenation, kashida and WriteHtml tests pass when run on their own too (76 tests).
• Golden masters regenerated from cold: tests/Mpdf/tmp/mpdf, tmp/mpdf and tmp/ttfontdata deleted, then fontcache:update, otldump:update, shaping:update and subset:update for all fonts. git status -- tests/data stays empty.
• composer cs is clean.
• phpstan: 33 errors, the known baseline skew, all in Gif/* and Writer/FontWriter.php. None are in touched files.

Refs #160, #191, #192.

🤖 Generated with Claude Code

[jakejackson1]

Rebased: #190 was squash-merged into gravitypdf (f9b3c0e), so this stack still carried its pre-squash commits. Retargeted to gravitypdf and rebased with --onto gravitypdf e5db3e5. Only this PR's own four commits remain; no conflicts. Suite, snapshots and cs pass on the new head, with no fixture movement.