mb_eregi_replace()

Purpose

mb_eregi_replace() searches a string for matches of a regular expression and replaces each match with replacement text. Two things set it apart. The match ignores case, and the pattern and subject are processed as multibyte characters in the current regex encoding. It belongs to the mb_ereg_* family, which uses Oniguruma syntax and does not use the delimiters that preg_* functions need.

This function is the case-insensitive sibling of mb_ereg_replace(). Use it when you need a case-blind replacement over text containing non-ASCII letters, such as accented Latin characters.

Signature

Parameters and defaults

• $pattern: the regular expression. Multibyte characters are allowed, and case is ignored. Do not wrap it in delimiters such as /; they would be treated as literal characters.
• $replacement: the text that replaces each match. It can refer back to captured groups with sequences such as \1.
• $string: the subject text to search.
• $options: optional search options, null by default. See mb_regex_set_options() for what the option letters mean. Since PHP 8.0 this parameter is explicitly nullable.

The character encoding comes from the internal encoding, or from mb_regex_encoding() if you set it. Setting it explicitly makes your code independent of other configuration.

Return value and failure cases

On success you get the resulting string. If nothing matches, that is the original string unchanged. The documented failure results are:

• false when an error occurs, for example when the pattern is not a valid regular expression.
• null when $string is not valid for the current encoding. Since PHP 7.1 the function checks this.

Because an empty string is also a legitimate result, compare failures strictly with === false or === null rather than relying on truthiness.

Example 1: ignoring ASCII case

Every spelling of the word is replaced, because case does not matter.

<?php
echo mb_eregi_replace('php', 'PHP 8.4', 'I like php and Php.'), "\n";

I like PHP 8.4 and PHP 8.4.

Example 2: multibyte letters

With the encoding set to UTF-8, the accented capital and lowercase forms are treated as the same letter.

<?php
mb_regex_encoding('UTF-8');
echo mb_eregi_replace('école', 'school', 'Une ÉCOLE, une école.'), "\n";

Une school, une school.

Example 3: reusing a captured group

The replacement can insert text captured by a group. The captured text keeps its original case, even though the match itself ignored case.

<?php
echo mb_eregi_replace('(\w+)@example\.com', '\1 at example', 'Mail ADA@EXAMPLE.COM now'), "\n";

Mail ADA at example now

Edge cases

• No match: the input string is returned as it was. This is not an error.
• Invalid input bytes: a subject that is malformed for the active encoding yields null, not a partially processed string. Validate or convert untrusted input first, for example with mb_check_encoding().
• Encoding mismatch: if the regex encoding is not the encoding of your text, matching can behave unexpectedly. Call mb_regex_encoding() before the replacement when your data is UTF-8 and the default might differ.
• Special characters in literals: characters such as ., ( and + keep their regex meaning. If you want to match user-supplied text literally, escape it first, for example with mb_ereg_replace()-compatible escaping done by you or a fixed pattern.
• The e option: the manual notes that the e modifier was deprecated in PHP 7.1 and warns never to use it with untrusted input, because nothing is escaped automatically. Do not use it.

Common mistakes

1. Adding delimiters. Writing '/php/i' searches for the slashes and the letters i literally. The mb_ereg_* functions take a bare pattern.
2. Expecting preg_replace() syntax. The pattern dialect and the replacement back-reference conventions are those of the mb_ereg family, so do not assume every PCRE feature exists.
3. Testing the result with if (!$result). An empty string, false and null are all falsy, yet they mean different things. Use strict comparisons.
4. Ignoring the encoding. Case folding of non-ASCII letters depends on the encoding being correct. A wrong encoding gives wrong matches or null.
5. Passing the options string for case folding. The function already ignores case; you do not need to ask for it again.

Related functions

• mb_ereg_replace(): the same replacement, but case-sensitive by default.
• mb_regex_encoding(): gets or sets the encoding used by the regex functions.
• mb_regex_set_options(): explains and sets the option letters accepted by $options.
• preg_replace(): the PCRE-based alternative, with delimiters and modifiers.

Recap

mb_eregi_replace() replaces regex matches while ignoring case and respecting multibyte characters. Give it a bare pattern, set the regex encoding explicitly, and treat false (error) and null (invalid string for the encoding) as distinct failures checked with strict comparison.