PHP RFC: Grapheme cluster for str_split function: grapheme_str_split

• Version: 0.1
• Date: 2024-03-04
• Author: Yuya Hamada, youkidearitai@gmail.com
• Status: Implemented
• Target Version: PHP 8.4
• Implementation: https://github.com/php/php-src/pull/13580
• First Published at: http://wiki.php.net/rfc/grapheme_str_split

I noticed PHP does not have a grapheme cluster based str_split function. So I think need str_split for grapheme cluster, grapheme_str_split function using ICU. Creating this function in the Intl extension would provide stronger support for grapheme clusters. This feature will allow to correctly handle emoji and Variation Selectors.

grapheme_str_split function is correctly support for grapheme cluster.

$ sapi/cli/php -r 'var_dump(grapheme_str_split("🙇‍♂️"));'
array(1) {
  [0]=>
  string(13) "🙇‍♂️"
}

For example, compare to mb_str_split function, mb_str_split function is str_split for Unicode codepoint. (Of course, sometimes this is more convenient.)

$ sapi/cli/php -r 'var_dump(mb_str_split("🙇‍♂️"));'
array(4) {
  [0]=>
  string(4) "🙇"
  [1]=>
  string(3) "‍" // U+200D Zero Width Joinner
  [2]=>
  string(3) "♂"
  [3]=>
  string(3) "️" // U+FE0F VARIATION SELECTOR
}

Until now, PCRE functions were required to support grapheme clusters.

$ sapi/cli/php -r  'preg_match_all("/(\X)/u", "🙇‍♂️", $matches, PREG_OFFSET_CAPTURE); var_dump($matches[1]);'
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(13) "🙇‍♂️"
    [1]=>
    int(0)
  }
}

Examples of other languages. Ruby is already support grapheme clusters as String#grapheme_clusters

s = "\u0061\u0308-pqr-\u0062\u0308-xyz-\u0063\u0308" # => "ä-pqr-b̈-xyz-c̈"
s.grapheme_clusters
# => ["ä", "-", "p", "q", "r", "-", "b̈", "-", "x", "y", "z", "-", "c̈"]

grapheme_str_split support to grapheme clusters (variation selectors).

$ sapi/cli/php -r 'var_dump(grapheme_str_split("ä-pqr-b̈-xyz-c̈"));'
array(13) {
  [0]=>
  string(2) "ä"
  [1]=>
  string(1) "-"
  [2]=>
  string(1) "p"
  [3]=>
  string(1) "q"
  [4]=>
  string(1) "r"
  [5]=>
  string(1) "-"
  [6]=>
  string(3) "b̈"
  [7]=>
  string(1) "-"
  [8]=>
  string(1) "x"
  [9]=>
  string(1) "y"
  [10]=>
  string(1) "z"
  [11]=>
  string(1) "-"
  [12]=>
  string(3) "c̈"
}

Add grapheme_str_split function.

function grapheme_str_split(string $string, int $length = 1): array|false {}

$string is only support UTF-8. $length is the length of the grapheme cluster per element of the array.

This could break a function existing in userland with the same name.

PHP 8.4

To SAPIs Will add the aforementioned functions to all PHP environments.

Add grapheme_str_split() to the intl extension.

No effect.

No new constants.

No changed php.ini settings.

No issues

This section details areas where the feature might be improved in future, but that are not currently proposed in this RFC.

https://github.com/php/php-src/pull/13580

Keep this updated with features that were discussed on the mail lists.