Stdlib: grapheme_str_split() — PHP 8.4 grapheme cluster split (ext/intl/grapheme)

[PurHur]

Category

stdlib · php-src-strict

Status (expanded 2026-06-06 — implementation-ready)

PHP 8.4 adds grapheme_str_split() (note underscore). Distinct from legacy grapheme_strsplit() tracked in #6246 — implement both names if php-src registers aliases; primary symbol is grapheme_str_split.

Problem

grapheme_str_split() is not implemented — function_exists('grapheme_str_split') is false. Zend splits a string into an array of grapheme clusters (Unicode extended grapheme cluster rules), distinct from byte/character str_split().

Complements #3352 umbrella and #5914 enum operand guards.

php-src reference

• php/php-src ext/intl/grapheme/grapheme_string.c — PHP_FUNCTION(grapheme_str_split) (PHP 8.4)
• php/php-src ext/intl/grapheme/grapheme_util.c — cluster iteration
• ICU/grapheme break iteration via ext/intl (prefer PHP in ext/intl/; thin ABI only if unavoidable)

Repro

test/repro-maintainer/grapheme_str_split_missing.php:

<?php
declare(strict_types=1);

if (!function_exists('grapheme_str_split')) {
    fwrite(STDERR, "MISSING grapheme_str_split\n");
    exit(1);
}

// Single grapheme: e + combining acute
$one = grapheme_str_split("e\xCC\x81");
var_export($one);
echo "\n";

// ASCII — one grapheme per char
$ascii = grapheme_str_split('abc');
var_export($ascii);
echo "\n";

// Optional length argument (max graphemes per chunk) — Zend 8.4+
if (function_exists('grapheme_str_split')) {
    $chunked = grapheme_str_split('abcdef', 2);
    var_export($chunked);
    echo "\n";
}

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php test/repro-maintainer/grapheme_str_split_missing.php 2>/dev/null || echo "Zend: needs PHP 8.4+ intl"
php bin/vm.php test/repro-maintainer/grapheme_str_split_missing.php 2>&1 | head -5
'

Check	Zend 8.4+ (intl)	VM today
function_exists('grapheme_str_split')	true	false
grapheme_str_split("e\xCC\x81")	array(1) { [0]=> string(3) ... }	undefined function
grapheme_str_split('abc')	three single-char strings	undefined function
grapheme_str_split('abcdef', 2)	chunked grapheme arrays	undefined function

php-src-strict: enum case string operands must TypeError (#5914).

Scope

Area	Files
ext	ext/intl/grapheme_str_split.php — register in ext/intl/Module.php
VM	PHP grapheme cluster boundaries (ICU or bundled table); no permanent C-only builtin
JIT/AOT	VM-only v1 OK; document in capability matrix
Tests	test/compliance/cases/stdlib/grapheme_str_split.phpt

Done when

• Repro script exits 0 on VM; outputs match Zend table above
• Optional $length argument matches Zend when non-null
• Enum-case operands TypeError (compliance case or shared with Stdlib: grapheme_*() — enum case string operands must TypeError (ext/intl/grapheme) #5914)
• ./script/ci-fast.sh --filter grapheme_str_split green
• script/capability-matrix.php row added

Verification

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

Related

• Stdlib: grapheme_* — Unicode grapheme cluster string API (ext/intl/grapheme parity) #3352 grapheme umbrella · Stdlib: grapheme_strsplit() — ICU grapheme cluster split missing (ext/intl/grapheme) #6246 grapheme_strsplit() legacy name · Stdlib: grapheme_levenshtein() — ICU grapheme edit distance missing (ext/intl/grapheme) #6998 grapheme_levenshtein() · Stdlib: grapheme_*() — enum case string operands must TypeError (ext/intl/grapheme) #5914 enum operands · Bootstrap: ext/intl/ module skeleton — register intl classes for self-host (M4) #5774 ext/intl skeleton · Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

[PurHur]

claim: PHP Compiler STD Lib — starting this run

[PurHur]

Merged via #7970

PHP path: VmGrapheme::strSplit() in ext/intl/VmGrapheme.php; procedural handler ext/intl/grapheme_str_split.php.

C shrink: 0 lines (no runtime/ changes).

Verification (green):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
php bin/vm.php test/repro-maintainer/grapheme_str_split_missing.php
./vendor/bin/phpunit --filter grapheme_str_split
'
# repro: single grapheme e+combining, abc split, chunked abcdef/2
# PHPUnit: OK (3 tests)

JIT runtime deferred (VM-only v1); enum operand TypeError via existing string guards.