Definition and Usage

PHP Version
4+

The strpos() function for strings searches for the specified substring in a string and returns the index of its first occurrence. If the specified substring is not found, it returns false.

This function is useful for finding the position of a substring in a string or for checking whether the substring exists.

Features

  • The comparison is case-sensitive.
  • This function does not support multi-byte strings such as Japanese, Korean, or Chinese.
  • Before str_contains() was introduced in PHP 8.0.0, the strpos() function was commonly used to check if a string contains a specific substring.

Additional Explanation
The str_contains() function, introduced in PHP 8.0.0, performs a case-sensitive check and returns true if the specified substring exists within the string, or false otherwise.

Basic Example

PHP 
$str = 'Hello, World!';
$substring = 'World';

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

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

// Output: Found at position: 7

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

Syntax

PHP 
strpos(string $haystack, string $needle, int $offset = 0): int|false

Parameters

Description of the parameters used in the 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.

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 strpos() function
VersionDescription
8.0.0 Empty strings ('') are now allowed for the $needle parameter.
8.0.0 Passing an integer (int) to the $needle parameter is no longer supported.
7.3.0 Passing an integer (int) to the $needle parameter has been deprecated.
7.1.0 Negative values are now allowed for the $offset parameter.

Things to Keep in Mind

The strpos() function is case-sensitive.

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

$pos = 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 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 = 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 = strpos($str, $substring); // Warning: strpos(): Empty needle 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 = 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.

The strpos() function does not support multi-byte strings such as Japanese, Korean, or Chinese. When used with multi-byte characters, it may return unexpected results.

Additional Explanation
English letters and numbers use 1 byte per character, while characters such as Japanese, Korean, or Chinese use 2 bytes or more. Strings that use more than one byte per character are referred to as "multi-byte" strings.

PHP 
$str = 'Nice to meet you. Welcome!';
$substring = 'Welcome';

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

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

// Output: Found at position: 18 <= unexpected result for multi-byte strings

The mb_strpos() function behaves almost the same as strpos() but properly handles multi-byte strings.

For strings containing multi-byte characters (such as Japanese, Korean, or Chinese), use mb_strpos() instead.

Practical Examples

The strpos() function is commonly used to search for a substring in a case-sensitive way.
Here are several examples showing practical use cases of strpos().

File Systems and Paths

Most file systems are case-sensitive. Therefore, when working with file names or directory paths, you must match the exact case of characters.

PHP 
$file_path = '/var/www/html/project/files/document.txt';
$directory_name = '/var/www/html/project';

// Check if the file path contains a specific directory
if (strpos($file_path, $directory_name) !== false) {
    echo 'The file belongs to the specified directory.';
} else {
    echo 'The file does not belong to the specified directory.';
}

// Output: 'The file belongs to the specified directory.'

// Extract the file name from the path
$file_name = substr($file_path, strrpos($file_path, '/') + 1);
echo "File name: $file_name";

// Output: "File name: document.txt"

In this example, the strpos() function checks whether a file path includes a specific directory, and the substr() and strrpos() functions are used together to extract the file name from the full path.

Note:
When working with file paths, it’s important to handle strings accurately and safely. PHP provides several functions to help with this—such as realpath() for normalizing paths and pathinfo() for retrieving detailed path information. Using these functions is generally safer and more reliable than manual string manipulation.

References

See also