Searching Strings for Substrings in PHP

PHP provides several functions that search for one string within another. Some return the location of the found string (strpos, strrpos and related), and others return part of the original string (strstr and strrchr). The search functions return false if the string you are searching for is not found within the original.

If your goal is simply to determine whether one string exists within another, the most efficient option is strpos.

strpos

The strpos function searches its first string argument for its second and returns the zero-based index location of the first match within the string, or false if it is not found. The following example demonstrates:

// example string to use for searches
$str = "We need to find the needle in the haystack.";

// search for the first occurrence of 'need' within $str
$pos = strpos($str, 'need');
// display type and value of $pos
var_dump($pos); // int(3)

Although we demonstrated the result using var_dump above, a typical examination of the return value for strpos is performed as follows:

// how to inspect strpos return value ($pos)
if ( $pos !== false ) { // if search string found
    echo "found it at location $pos";
} else { 
    echo "not found.";
}

Be sure to use the === or !== operators to compare the strpos function's return value to false. If the substring is found at the start of the string, strpos will return 0, which the == or != operators would convert to false.

You can specify an offset to begin the search a specified number of characters from the start of the string, as this example demonstrates:

/* strpos arguments:
 * subject string (aka haystack), search string (needle), offset (optional) */
// start search for 'need' from character 10 in $str
$pos = strpos($str, 'need', 10); // 20

When starting the search from character 10, the result is 20, the index location of the start of the word needle.

strrpos

The strrpos function finds the position of the last occurrence of a substring in a string:

// example string to use for searches
$str = "We need to find the needle in the haystack.";

// find location of last occurrence of 'need' in $str
$pos = strrpos($str, 'need'); // 20

The strrpos function also provides an optional offset parameter which can be either positive or negative. If the offset is positive, that number of characters at the beginning of the string will be excluded from the search. Consider the following example:

// search from right for 'We' excluding first 3 characters
$pos = strrpos($str, 'We', 3);
var_dump($pos); // bool(false)

The result is false since 'We' is not found when the search excludes the first three characters.

If the offset is negative, that many characters at the end of the string are excluded from the search. We demonstrate with two searches specifying a negative offset:

// search from right for 'hay' excluding last 5 characters
$pos = strrpos($str, 'hay', -5); // int(34)

// search from right excluding last 10 characters
$pos = strrpos($str, 'hay', -10); // bool(false)

The last result above is false since 'hay' is not found when the search excludes the last 10 characters.

Notice that the return value of the strrpos function gives the location from the start of the string, even though the search commences from the right.

stripos and strripos

The strpos and strrpos functions perform case-sensitive searches. PHP provides stripos and strripos functions to perform case-insensitive searches. They work just like their case-sensitive equivalents:

// example string to use for searches
$str = "We need to find the needle in the haystack.";

// do case-insensitive search for 'we'
$pos = stripos($str, 'we'); // int(0)

// do case-insensitive search from right for 'Need'
$pos = strripos($str, 'Need'); // int(20)

The case-insensitive search for 'we' results in 0, indicating it was found at the beginning of the string we are searching in. The case-insensitive search for 'Need' from the right (using strripos), finds it at location 20.

strstr

The strstr function searches the first string argument for the second. If the second is found within the first, strstr returns the portion of the original string starting from the first found occurrence to the end of the string.

// example string
$str = "We need to find the needle in the haystack.";

// search for 'the' in $str
$newstr = strstr($str, 'the');
var_dump($newstr); // string(27) "the needle in the haystack." 

The strstr function returns the first 'the' it finds, along with the rest of the original string.

If you pass true as the third argument to strstr, the portion of the original string before the found string is returned:

// pass true to return the part of $str before 'the'
$newstr = strstr($str, 'the', true);
var_dump($newstr); // string(16) "We need to find " 

This time the strstr function returns everything before the first 'the' in the string.

PHP also provides the stristr function which works exactly the same as strstr except that it performs a case-insensitive search.

strrchr

The strrchr function searches the first string argument from the right for the character we specify in the second argument. The function returns the portion of the string from the location of the found instance of that character to the end of the string:

// example string
$str = "We need to find the needle in the haystack.";

// search from right for 's' in $str
$newstr = strstr($str, 's');
var_dump($newstr); // string(6) "stack." 

Notice that unlike strstr, if the second argument consists of multiple characters, only the first is used:

// test with multi-character second argument
$newstr = strrchr($str, 'the');
var_dump($newstr); // string(5) "tack."

Instead of returning 'the haystack', the strrchr function returns 'tack', applying only the first letter of the second argument to the search.