mb_regex_set_options()

Purpose

mb_regex_set_options() reads or changes the default options used by PHP's multibyte regex family, the mb_ereg*() functions and mb_split(). These functions run on the Oniguruma engine, and the engine needs two kinds of configuration: options (such as case-insensitive matching) and a syntax mode (such as Ruby or Perl style). This function handles both through one compact string.

The setting is global state for the current request. Changing it affects every later mbregex call that does not supply its own options, so careful code restores the old value when it is done.

This function does not configure the PCRE preg_*() functions. Those take their flags from the pattern itself.

Signature

Parameters and defaults

$options is a string in which each character stands for one option or mode. It defaults to null, which means "do not change anything, just report the current setting".

The option characters are:

• i: ambiguity (case-insensitive) matching
• x: extended pattern form
• m: . also matches newlines
• s: ^ becomes \A and $ becomes \Z
• p: the same as m and s together
• l: find the longest matches
• n: ignore empty matches

The syntax modes are j (Java), u (GNU regex), g (grep), c (Emacs), r (Ruby), z (Perl), b (POSIX Basic) and d (POSIX Extended). You may give several options but only one mode, and the mode character must come last in the string.

The old e option (eval the result) was removed in PHP 8.0. In PHP 8 it throws a ValueError. Do not pass it.

Return value and failure cases

The function always returns a string. Since PHP 8.0, when you pass a non-null $options, the return value is the previous options string. When you omit the argument or pass null, you get the current string. Before PHP 8.0 the setter returned the new options, so older code that relied on that behavior needs checking.

The default in a standard setup is pr, meaning the p option plus the Ruby syntax mode. The returned string is built in a fixed order: option letters first, then the mode letter.

Example 1: reading the current options

Calling the function with no argument is a safe way to inspect the state.

<?php
echo mb_regex_set_options(), "\n";

pr

Example 2: set, read and restore

Because the setter returns the previous value, you can save it and put it back later. This keeps the change local to one piece of code.

<?php
$previous = mb_regex_set_options('ir');
$current = mb_regex_set_options();
mb_regex_set_options($previous);
echo json_encode([$previous, $current, mb_regex_set_options()]), "\n";

["pr","ir","pr"]

The three values are the original setting, the temporary setting and the restored setting.

Example 3: changing the behavior of mb_ereg()

mb_ereg() takes its defaults from this setting. The same pattern fails by default, then matches once the i option is enabled.

<?php
$before = mb_ereg('HELLO', 'hello world');
$previous = mb_regex_set_options('ir');
$after = mb_ereg('HELLO', 'hello world');
mb_regex_set_options($previous);
echo json_encode([$before, $after]), "\n";

[false,true]

Edge cases

• Passing null or no argument never modifies anything.
• State is process-wide for the request. A library that changes the options can surprise unrelated code that runs afterwards.
• Include a mode character. The string describes the whole configuration, not an incremental change, so write something like ir rather than only i. Spelling out the mode makes the result predictable.
• Options given directly to a function (for example the third argument of mb_ereg()) apply to that call, while this function sets the fallback for calls that give none.
• Passing an empty string is a request to set an empty configuration, not a request to read. Use null to read.

Common mistakes

1. Expecting the new value back. In PHP 8 and later the setter returns the old value. Call it again with no argument if you need the current one.
2. Forgetting to restore. Leaving i or another option switched on can change matching far from where you set it.
3. Putting the mode first. The mode character must be the last one in the string, and only one mode is allowed.
4. Using e. It was removed and now raises a ValueError. Use mb_ereg_replace_callback() for computed replacements.
5. Mixing it up with PCRE. preg_match() ignores this setting. Its flags come from the pattern's modifiers.
6. Assuming a syntax character is harmless. Switching to a mode such as z (Perl) or b (POSIX Basic) changes how metacharacters are interpreted, so existing patterns may match differently.

Related functions

• mb_ereg() matches a pattern with multibyte support.
• mb_eregi() matches while always ignoring case.
• mb_split() splits a string using a multibyte regular expression.
• mb_regex_encoding() sets or gets the character encoding the mbregex functions use.

Recap

mb_regex_set_options() gets or sets the default options and syntax mode for the mbregex functions. Pass null to read. Pass a string with the mode last to set it, and note that PHP 8 returns the previous string. Save that value and restore it after a temporary change.