Definition and Usage

PHP Version
5.2+

mb_stripos() function searches for the position of a substring in a string.

Similar to stripos(), but designed to safely handle multibyte character encodings such as UTF-8.

Features

  • This function does support multi-byte strings such as Japanese, Korean, or Chinese.
  • Returns the position (index) of the first occurrence of the specified substring within the target string.
  • Returns false if the specified substring is not found.
  • The comparison is case-insensitive.

Basic Example

PHP 
$haystack = 'こんにちは、PHPのmb_stripos()関数の例です。'; // 'Hello, this is a PHP mb_stripos() function example.'
$needle = 'php';

$position = mb_stripos($haystack, $needle);

if ($position !== false) {
    echo 'Found at position: ' . $position;
} else {
    echo 'Substring not found.';
}

// Output: Found at position: 6

/*
 * Note:
 * In PHP, string indexes start at 0.
 * The index of the first character is 0, the second character is 1, and so on.
 */

Issues with stripos() for Multibyte Strings

The stripos() function does not handle multibyte characters correctly, which can lead to unexpected results.

While ASCII characters such as English letters and digits use 1 byte, characters in languages such as Japanese, Korean, and Chinese may be represented with multiple bytes. Strings that use more than 1 byte per character are called "multibyte strings".

PHP 
$haystack = 'こんにちは、PHPのmb_stripos()関数の例です。'; // 'Hello, this is a PHP mb_stripos() function example.'
$needle = 'php';

$position = stripos($haystack, $needle);

if ($position !== false) {
    echo 'Found at position: ' . $position;
} else {
    echo 'Substring not found.';
}

// Output: Found at position: 18  <= Unexpected result (byte offset)

In UTF-8 and other multibyte encodings, a single character may be represented by multiple bytes. Using stripos(), which counts bytes rather than characters, can therefore return unexpected positions for multibyte strings.

Solving the Problem with mb_stripos()

The mb_stripos() function is designed to safely handle multibyte strings, including Japanese, Korean, and Chinese text. It returns the correct character position, making it the recommended alternative to stripos() when working with multibyte-encoded strings.

Note:
mb_stripos() functions as a multibyte-safe replacement for stripos(), preventing the common pitfalls associated with byte-based string functions.

Syntax

PHP 
mb_stripos(
    string $haystack,
    string $needle,
    int $offset = 0,
    ?string $encoding = null
): int|false

Parameters

Description of the parameters used in the mb_stripos() function
$haystack The input string to be searched.
$needle The substring to search for.
  • The comparison is case-sensitive.
  • In versions prior to PHP 8.0.0, an empty string ('') is not allowed and will trigger a warning error.
$offset Optional. The zero-based index at which to start the search.
  • If omitted, the default value is 0.
  • As of PHP 7.1.0, negative values are allowed. When a negative value is given, the search starts that many characters from the end of the string.
$encoding Optional. Specifies the character encoding of the string.
The default value is null. If you are using a standard encoding such as UTF-8, you do not need to specify it. If omitted or null, the internal character encoding value will be used.

Return Values

Returns the position (index) of the first occurrence of the specified substring ($needle) within the input string ($haystack).

Note:
String positions (indexes) start at 0, not 1.

Returns false if the specified substring ($needle) is not found.

Changelog

Version history of the mb_stripos() function
VersionDescription
8.0.0 Empty strings ('') are now allowed for the $needle parameter.
8.0.0 The $encoding parameter can now accept null as a value.
7.1.0 Negative values are now allowed for the $offset parameter.

Things to Keep in Mind

The mb_stripos() function performs a case-insensitive search.
If you need a case-sensitive search, use the mb_strpos() function instead.

String indexes start at 0.
The first character has an index of 0, and the second character has an index of 1.

PHP String indexes start at 0. 
$newstring = 'こんにちは';
$pos = mb_stripos($newstring, 'こ');

var_dump($pos); // int(0)

Be careful when using this function's return value in a Boolean context.
To properly test the return value, always use the === operator.

If the specified substring ($needle) is found at the very beginning of the string ($haystack), the function returns 0.

However, because 0 is loosely evaluated as false in PHP, using == may lead to incorrect results. For strict comparison, use ===.

PHP Always use the === operator when testing the return value. 
$str = 'Hello, World!';
$substring = 'hello';

$pos = mb_stripos($str, $substring);

var_dump($pos); // int(0)

if ($pos === false) {
    echo "The string 'hello' was not found.";
} else {
    echo "The string 'hello' is included in the text.";
}

// Output: The string 'hello' is included in the text.

In versions prior to PHP 8.0.0, empty strings ('') are not allowed as the search string ($needle), and doing so triggers a warning error.

PHP In PHP versions before 8.0.0, an empty string ('') is not allowed as the search string. 
$str = 'Hello, World!';
$substring = '';

$pos = mb_stripos($str, $substring); // Warning: mb_stripos(): Empty delimiter in

References

See also