# RFC: Grapheme cluster for str_split function: grapheme_str_split

- Status: Implemented (PHP 8.4)
- Authors: Yuya Hamada, youkidearitai@gmail.com
- Date: 2024-03-04
- Version: 0.1
- Target: PHP 8.4
- Implementation: https://github.com/php/php-src/pull/13580
- Original: https://wiki.php.net/rfc/grapheme_str_split
- Page: https://externals.io/rfc/grapheme_str_split
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Add grapheme cluster for str_split function: grapheme_str_split (closed)

Yes: 19 · No: 0

Voters: ashnazg (Yes), beberlei (Yes), crell (Yes), dams (Yes), derick (Yes), devnexen (Yes), galvao (Yes), imsop (Yes), jimw (Yes), jwage (Yes), mcmic (Yes), nicolasgrekas (Yes), nielsdos (Yes), ocramius (Yes), petk (Yes), saki (Yes), sergey (Yes), theodorejb (Yes), weierophinney (Yes)

## Discussions on the mailing list

- [\[RFC\] grapheme cluster for str_split, grapheme_str_split function](https://externals.io/message/122588.md) — started on 2024-03-09, 12 messages
- [Updates needed to various RFCs](https://externals.io/message/124843.md) — started on 2024-08-11, 11 messages

---

## Introduction

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](https://unicode-org.github.io/icu/userguide/icu4c/). 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](https://ruby-doc.org/3.2.2/String.html#method-i-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̈"
}
```

## Proposal

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.

## Backward Incompatible Changes

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

## Proposed PHP Version(s)

PHP 8.4

## RFC Impact

### To SAPIs

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

### To Existing Extensions

Add grapheme\_str\_split() to the intl extension.

### To Opcache

No effect.

### New Constants

No new constants.

### php.ini Defaults

No changed php.ini settings.

## Open Issues

No issues

## Future Scope

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

## Proposed Voting Choices

**Vote: Add grapheme cluster for str\_split function: grapheme\_str\_split** — Yes: 19 · No: 0 (closed)

## Implementation

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

## Rejected Features

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