PHP strpos(): Find the Position of a Substring

strpos($haystack, $needle) returns the position of the first $needle inside $haystack, counted from 0, or false if it is not there. Always test the result with !== false, because a match at the start returns 0.

<?php
$text = 'apple, banana, cherry';

var_dump(strpos($text, 'banana'));   // found at position 7
var_dump(strpos($text, 'apple'));    // found at position 0
var_dump(strpos($text, 'grape'));    // not found

if (strpos($text, 'apple') !== false) {
    echo "Found apple\n";
}

If you only need a yes or no answer on PHP 8, str_contains() is clearer. Use strpos() when the position matters.

Syntax

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

The search is case-sensitive. $offset tells it where to start looking; a negative offset counts from the end of the string.

The !== false pitfall

0 and false are equal under loose comparison (==). A match at position 0 is therefore treated as "not found" by any check that is not strict.

<?php
$url = 'https://example.com';

// Wrong: position 0 is falsy, so this says "no"
if (strpos($url, 'https')) {
    echo "wrong check: has https\n";
} else {
    echo "wrong check: no https\n";
}

// Right: compare strictly with false
if (strpos($url, 'https') !== false) {
    echo "right check: has https\n";
}

The same rule applies to stripos(), strrpos() and array_search(), which can all return 0 for a real match.

Case-insensitive search with stripos

stripos() takes the same arguments and ignores the case of ASCII letters.

<?php
$title = 'Learning PHP the Hard Way';

var_dump(strpos($title, 'php'));    // case-sensitive: not found
var_dump(stripos($title, 'php'));   // found at 9

Find the last occurrence with strrpos

strrpos() returns the position of the last match. It is the standard way to get a file extension or the last segment of a path.

<?php
$file = 'archive.backup.tar.gz';

$dot = strrpos($file, '.');
echo substr($file, $dot + 1), "\n";      // gz
echo substr($file, 0, $dot), "\n";       // archive.backup.tar

$path = '/var/www/html/index.php';
echo substr($path, strrpos($path, '/') + 1), "\n";

For file names specifically, pathinfo($file, PATHINFO_EXTENSION) does this for you. Cutting the string at the position is covered on the substr() page.

Start the search at an offset

The third argument skips the beginning of the string. A negative offset starts that many characters before the end.

<?php
$s = 'one two one two';

var_dump(strpos($s, 'one'));        // 0
var_dump(strpos($s, 'one', 1));     // skip position 0: finds the second one
var_dump(strpos($s, 'two', -3));    // search only the last 3 characters

Find all occurrences

strpos() finds one match. Loop and move the offset past each match to find all of them:

<?php
$text = 'the cat sat on the mat with the hat';
$needle = 'the';

$positions = [];
$offset = 0;
while (($pos = strpos($text, $needle, $offset)) !== false) {
    $positions[] = $pos;
    $offset = $pos + strlen($needle);
}

print_r($positions);
echo count($positions), " matches\n";

Only the count? substr_count($text, 'the') is shorter. For patterns, preg_match_all() with PREG_OFFSET_CAPTURE returns every match with its position.

Japanese text: byte position vs character position

strpos() finds multibyte text correctly, but the number it returns is in bytes. Kana and common kanji take 3 bytes each in UTF-8, so in all-Japanese text the byte position is three times the character position, and in mixed text the two drift apart in less obvious ways. mb_strpos() returns characters, which is what mb_substr() expects.

<?php
$s = '東京都渋谷区';

var_dump(strpos($s, '渋谷'));      // byte position
var_dump(mb_strpos($s, '渋谷'));   // character position

echo mb_substr($s, mb_strpos($s, '渋谷')), "\n";

Mixing the two is a classic bug: passing a strpos() result to mb_substr() starts too far into the string. Use strpos with substr, and mb_strpos with mb_substr.