Stdlib: mb_substr / mb_strpos / mb_strtolower — mbstring beyond mb_strlen (ext/mbstring parity)

[PurHur]

Category

stdlib

Problem

Only mb_strlen() is registered (ext/types/mb_strlen.php). Multibyte string manipulation — required for UTF-8 web apps and #3222 charset work — is missing:

• mb_substr, mb_strpos, mb_strrpos, mb_strtolower, mb_strtoupper
• mb_strlen with explicit encoding (verify parity)

php-src reference

• ext/mbstring/mbstring.c — php_mb_substr, php_mb_strpos, case conversion
• ext/mbstring/php_unicode.c — UTF-8 codepoint iteration
• ext/standard/basic_functions.c — strlen fallback when mbstring disabled

Repro (today)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php bin/vm.php -r "var_dump(function_exists(\"mb_substr\"));"
php bin/vm.php -r "echo mb_substr(\"café\", 0, 2, \"UTF-8\");"
'

Zend PHP (mbstring): bool(true); prints ca (or codepoint-safe slice per encoding)
This compiler: Call to undefined function mb_substr()

Compare with working mb_strlen:

php bin/vm.php -r "echo mb_strlen(\"café\");"

Scope (this repo)

Layer	Files	Notes
VM	ext/types/mb_substr.php, VmMbstring.php	UTF-8 v1 via mb_* polyfill or host ext/mbstring when embedding Zend for dev
Module	ext/types/Module.php or ext/standard/Module.php	Register mb_* family
JIT	defer	VM-only v1
Tests	test/compliance/cases/mb_substr_utf8.phpt	Non-ASCII fixtures

v1 encoding: UTF-8 only; other encodings → ValueError or documented subset.

Done when

• mb_substr('café', 0, 2, 'UTF-8') matches Zend on VM
• mb_strpos, mb_strtolower registered with compliance PHPTs
• ./script/ci-fast.sh --filter mb_substr green
• docs/capabilities.md lists mb_* rows

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter mb_substr'

Dependencies

• Stdlib: iconv() / mb_convert_encoding() — charset conversion (ext/iconv + ext/mbstring parity) #3222 iconv / mb_convert_encoding — complementary charset stack
• Existing ext/types/mb_strlen.php — share helper module

Links

• Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 — UTF-8 source files in lib/ benefit from mb_* in compiled runtime

[PurHur]

Implementation-ready expansion (parity architect run 2026-06-03)

Done when

• function_exists('mb_substr'), mb_strpos, mb_strtolower, mb_strtoupper return true on bin/vm.php
• UTF-8 repro: mb_substr("café", 0, 2, "UTF-8") matches Zend (ca for bytes 0–1 of UTF-8 string per php-src)
• Invalid encoding → ValueError with Zend message (verify against ext/mbstring/mbstring.c)
• mb_strlen($s, $enc) with non-UTF-8 encoding matches Zend when host mbstring available OR documented VM-only path for bootstrap
• Compliance PHPTs under test/compliance/cases/stdlib/mb_*.phpt pass VMTest
• Capability matrix regenerated (php script/capability-matrix.php)

Scope table (complete)

Layer	Path	Notes
VM builtins	ext/types/mb_substr.php, mb_strpos.php, … (new)	Mirror mb_strlen.php pattern; use VmString / UTF-8 iterator
Registration	ext/types/Module.php or ext/standard/Module.php	Same module as mb_strlen
JIT (v2)	ext/types/JitMb*.php	Optional follow-up; VM-first acceptable for #3222 dependency
Tests	test/compliance/cases/stdlib/mb_substr_utf8.phpt, etc.

Verification commands

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php bin/vm.php -r "var_dump(function_exists(\"mb_substr\"));"
php bin/vm.php test/compliance/cases/stdlib/mb_substr_utf8.phpt
'

Related

• Stdlib: iconv() / mb_convert_encoding() — charset conversion (ext/iconv + ext/mbstring parity) #3222 (iconv / mb_convert_encoding) — charset conversion stack
• Stdlib: mb_strwidth() / mb_strimwidth() — display width (ext/mbstring/mbstring.c parity) #3495 (mb_strwidth) — display width follow-up

[PurHur]

claim: worker-lane-C — starting this run (lane C backlog is stdlib-only; #3239 lowest unclaimed implementation-ready issue in lane C % 3 == 2)

[PurHur]

Merged via #8440.

Verification

• Issue repro: function_exists('mb_substr') → true; mb_substr('café', 0, 2, 'UTF-8') → ca
• ./vendor/bin/phpunit --filter mb_substr_utf8 test/compliance/VMTest.php → OK

Implementation: PHP in ext/mbstring/ + VmMbstring UTF-8 helpers (php-src ext/mbstring/mbstring.c). VM-only v1; no C runtime changes.