Definition and Usage

PHP Version
4.0.6+

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

Similar to strpos(), 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-sensitive.

Basic Example

PHP 
$str = 'こんにちは。ようこそ！'; // "Hello. Welcome!"
$substring = 'ようこそ';           // "Welcome"

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

if ($pos !== false) {
    echo "Found at position: $pos";
} 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 strpos() for Multibyte Strings

The strpos() 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 
$str = 'こんにちは。ようこそ！'; // "Hello. Welcome!"
$substring = 'ようこそ';           // "Welcome"

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

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

// Output: Found at position: 18 <= Unexpected result

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

Solving the Problem with mb_strpos()

The mb_strpos() 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 strpos() when working with multibyte-encoded strings.

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

Syntax

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

Parameters

Description of the parameters used in the mb_strpos() 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_strpos() 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_strpos() function is case-sensitive.

PHP The mb_strpos() function is case-sensitive. 
$str = 'Hello, World!';
$substring = 'world';

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

if ($pos === false) {
    echo "Cannot find 'world!' because the case does not match.";
} else {
    echo "'world!' is included in the string.";
}

// Output: Cannot find 'world!' because the case does not match.

If you want to perform a case-insensitive search, use the mb_stripos() 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 = 'abcdef ghijk';
$pos = mb_strpos($newstring, 'a');

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

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_strpos($str, $substring); // Warning: mb_strpos(): Empty delimiter in

As of PHP 8.0.0, empty strings ('') are allowed.

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_strpos($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.

References

See also