mb_split
Splits a multibyte string into an array using a multibyte-aware regular expression pattern.
mb_split(string $pattern, string $string, int $limit = -1): array|false- Added in PHP 4.2.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$pattern | string | The regular expression pattern, written WITHOUT delimiters. Use "\s", not "/\s/". |
$string | string | The string being split. |
$limitoptional | int= -1 | Maximum number of elements to return. The last element holds the unsplit remainder. |
Return value
array|falseAn array of the split pieces, or false on failure.
Errors
Returns false on a failed match operation; an invalid pattern emits a warning rather than throwing.
mb_split() is the mbstring counterpart of preg_split(). It uses the Oniguruma regex engine and the encoding set by mb_regex_encoding(), so character classes and quantifiers count whole characters rather than bytes.
When to reach for it
Reach for it when you are already inside mbstring-land — you have called mb_regex_encoding(), you are using mb_ereg() elsewhere, or you need Oniguruma's encoding handling for something like Shift_JIS or EUC-JP that PCRE does not natively support. For plain UTF-8 work, preg_split() with the u modifier is faster, better documented and supports far more syntax (lookbehind, named groups, PREG_SPLIT_NO_EMPTY).
What trips people up
The pattern takes no delimiters. Passing "/\s/" does not error — it silently looks for a literal slash-whitespace-slash sequence, so you get back the whole string in a one-element array and think the function is broken.
The regex encoding is separate from the internal encoding. mb_internal_encoding('UTF-8') does not set it; you need mb_regex_encoding('UTF-8') too, or multibyte character classes will misbehave.
There is no flag to drop empty pieces, so splitting on a pattern that can match at the string edges leaves empty strings in the result.
Example
When to use it
- Split a Japanese CSV-like line on ideographic commas while running under Shift_JIS or EUC-JP
- Break a UTF-8 log line on runs of whitespace without PCRE's byte-oriented defaults
- Cap parsing at a fixed number of fields with limit, keeping the rest of the line in the final element
Frequently asked questions
What is the difference between mb_split and preg_split?
mb_split uses the Oniguruma engine and the encoding from mb_regex_encoding(), while preg_split uses PCRE and needs the u modifier for UTF-8. preg_split also takes delimiters, supports flags such as PREG_SPLIT_NO_EMPTY, and is generally faster, so prefer it unless you specifically need mbstring's regex encoding support.
Why does mb_split return the whole string in one element?
Almost always because the pattern was written with delimiters. mb_split takes a bare pattern, so use "," or "\\s" and never "/,/" or "/\\s/".
Do I need to call mb_regex_encoding before mb_split?
Yes, if you are splitting non-ASCII text. mb_split reads the regex encoding, which is set separately from mb_internal_encoding(), so call mb_regex_encoding('UTF-8') explicitly to be safe.
More examples
Split on a multibyte delimiter
The ideographic comma U+3001 is three bytes in UTF-8. Because mb_regex_encoding() is set to UTF-8, Oniguruma treats it as one character and the array comes back with six clean pieces.
<?php
mb_regex_encoding('UTF-8');
$words = mb_split('、', '日、に、本、ほん、語、ご');
print_r($words);
echo count($words), " pieces\n";Empty pieces at the edges
The first dump shows five elements, three of them empty strings, because the pattern matches at the start, in the middle and at the end. Unlike preg_split() there is no PREG_SPLIT_NO_EMPTY, so you filter the result yourself and re-index with array_values().
<?php
mb_regex_encoding('UTF-8');
var_dump(mb_split(',', ',a,,b,'));
// mb_split has no NO_EMPTY flag - filter afterwards
print_r(array_values(array_filter(mb_split(',', ',a,,b,'), 'strlen')));
Discussion