Stdlib: grapheme_* — Unicode grapheme cluster string API (ext/intl/grapheme parity)

[PurHur]

Category

stdlib

Status (refreshed 2026-06-18 — implementation-ready worker spec)

Partial landing (VM): ext/intl/VmGrapheme.php + ext/intl/grapheme_*.php register several helpers. Verified on bin/vm.php:

Function	function_exists (VM)	Notes
grapheme_strlen	✅ true	VM delegate
grapheme_substr	✅ true	VM delegate
grapheme_strpos / strstr / stripos / …	✅ true	see ext/intl/grapheme_*.php
grapheme_str_split	✅ true	#6246 — landed; JIT + compliance still open
grapheme_levenshtein	❌ false	#3352 slice

Remaining gaps: JIT/AOT lowering (most throw deferred), self-host without host ICU, enum-case operand TypeError guards (#5914), compliance PHPT coverage.

Problem

grapheme_* helpers from ext/intl provide user-visible string length/search/split on grapheme clusters (combining marks stay attached). Frameworks and Symfony String use them beyond byte/UTF-8 code units.

php-src reference

• php/php-src ext/intl/grapheme/grapheme_string.c — grapheme_strlen, grapheme_substr, grapheme_strpos, …
• php/php-src ext/intl/grapheme/grapheme_util.c — ICU grapheme break iterator

Repro — strlen/substr (VM should match Zend when host intl available)

Save as test/repro-maintainer/grapheme_strlen_substr.php:

<?php
declare(strict_types=1);

$s = "a\xCC\x81b"; // a + combining acute + b => 2 graphemes
echo grapheme_strlen($s), "\n";
echo bin2hex(grapheme_substr($s, 0, 1)), "\n";
echo grapheme_strpos($s, 'b'), "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php test/repro-maintainer/grapheme_strlen_substr.php
php bin/vm.php test/repro-maintainer/grapheme_strlen_substr.php'

Engine	grapheme_strlen	first cluster hex	strpos b
Zend + ext/intl	2	61cc81	2
VM (target)	same	same	same

Repro — missing grapheme_levenshtein

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php bin/vm.php test/repro-maintainer/grapheme_levenshtein_missing.php 2>&1 | head -3'
# MISSING grapheme_levenshtein

Scope (PHP-in-PHP)

Area	Path	Notes
VM	ext/intl/VmGrapheme.php, ext/intl/grapheme_*.php	ICU via host intl acceptable phase 1; document bootstrap path
JIT	ext/intl/JitGrapheme.php (new)	Remove "deferred" throws; pair with #5914 enum guards
Module	ext/intl/Module.php	Register all grapheme builtins
Tests	test/compliance/cases/stdlib/grapheme_*.phpt	strlen, substr, strpos, str_split, levenshtein
Matrix	php script/capability-matrix.php	JIT column updates

Not in scope here: full ext/intl ICU formatting (#3336, #5153 Normalizer).

Done when

• test/repro-maintainer/grapheme_strlen_substr.php matches Zend on VM
• grapheme_levenshtein registered with Zend parity on NFC/NFD sample (Stdlib: grapheme_* — Unicode grapheme cluster string API (ext/intl/grapheme parity) #3352 levenshtein slice)
• Enum-case string operands TypeError per Stdlib: grapheme_*() — enum case string operands must TypeError (ext/intl/grapheme) #5914 (shared compliance phpt)
• At least one grapheme builtin JIT-lowering green (or documented VM-only with matrix note)
• ./script/ci-fast.sh --filter grapheme green

Child / related issues

• Stdlib: grapheme_strsplit() — ICU grapheme cluster split missing (ext/intl/grapheme) #6246 grapheme_str_split (VM landed — close when JIT+PHPT green)
• Stdlib: grapheme_*() — enum case string operands must TypeError (ext/intl/grapheme) #5914 enum operand guards
• Stdlib: grapheme_* — Unicode grapheme cluster string API (ext/intl/grapheme parity) #3352 levenshtein · mbstring Stdlib: mb_substr / mb_strpos / mb_strtolower — mbstring beyond mb_strlen (ext/mbstring parity) #3239 · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

[PurHur]

claim: PHP Compiler STD Lib — starting this run (grapheme_substr/grapheme_strpos VM+JIT/AOT)

[PurHur]

Merged via #8482.

Implemented: grapheme_substr() and grapheme_strpos() in ext/intl/VmGrapheme.php (PHP-in-PHP, \X grapheme split — no host ext-intl, no C runtime). Registered in ext/intl/Module.php with JIT compile-time fold in JitGrapheme.

Verification (green):

• VM repro: combining acute cluster a\xCC\x81b → strlen=2, substr(0,1)=á, substr(1)=b, strpos('b')=1
• vendor/bin/phpunit --filter grapheme_substr → 5/5 OK (VM+JIT compliance)
• vendor/bin/phpunit test/unit/GraphemeSubstrStrposBuiltinTest.php → 3/3 OK
• php bin/compile.php -l test/fixtures/aot/compile-only/grapheme_substr_strpos_literals.php → exit 0

Remaining on #3352 umbrella: other grapheme_* helpers still open (e.g. grapheme_strpos siblings already partially covered by #6153/#7221 family).