PHP strpos(): encontrar a posição de uma substring

strpos($haystack, $needle) retorna a posição do primeiro $needle dentro de $haystack, contada a partir de 0, ou false se ele não estiver lá. Sempre teste o resultado com !== false, porque uma correspondência no início retorna 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";
}

Se você só precisa de uma resposta sim ou não no PHP 8, o str_contains() é mais claro. Use o strpos() quando a posição importar.

Sintaxe

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

A busca diferencia maiúsculas e minúsculas. $offset diz onde começar a procurar; um offset negativo conta a partir do fim da string.

A armadilha do !== false

0 e false são iguais na comparação frouxa (==). Uma correspondência na posição 0 é, portanto, tratada como "não encontrado" por qualquer verificação que não seja estrita.

<?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";
}

A mesma regra vale para stripos(), strrpos() e array_search(), que podem todos retornar 0 para uma correspondência real.

Busca sem diferenciar maiúsculas com stripos

O stripos() recebe os mesmos argumentos e ignora maiúsculas e minúsculas em letras ASCII.

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

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

Encontrar a última ocorrência com strrpos

O strrpos() retorna a posição da última correspondência. É o jeito padrão de pegar a extensão de um arquivo ou o último segmento de um caminho.

<?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";

Para nomes de arquivos especificamente, pathinfo($file, PATHINFO_EXTENSION) faz isso por você. Cortar a string na posição é explicado na página sobre substr().

Começar a busca num offset

O terceiro argumento pula o começo da string. Um offset negativo começa essa quantidade de caracteres antes do fim.

<?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

Encontrar todas as ocorrências

O strpos() encontra uma correspondência. Faça um loop e mova o offset para depois de cada correspondência para encontrar todas:

<?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";

Só a contagem? substr_count($text, 'the') é mais curto. Para padrões, preg_match_all() com PREG_OFFSET_CAPTURE retorna cada correspondência com a posição.

Texto em japonês: posição em bytes ou em caracteres

O strpos() encontra texto multibyte corretamente, mas o número que retorna está em bytes. Kana e kanji comuns ocupam 3 bytes cada em UTF-8, então num texto todo em japonês a posição em bytes é três vezes a posição em caracteres, e num texto misturado as duas se afastam de formas menos óbvias. O mb_strpos() retorna caracteres, que é o que o mb_substr() espera.

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

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

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

Misturar os dois é um bug clássico: passar um resultado do strpos() para o mb_substr() começa longe demais na string. Use strpos com substr, e mb_strpos com mb_substr.