strpos()

Introdução

A função strpos() no PHP encontra a posição da primeira ocorrência de uma substring dentro de outra string. Ela retorna o índice baseado em zero dessa ocorrência, ou o boolean false se a substring não for encontrada. É uma das funções de string mais utilizadas no PHP — você a usa sempre que precisa perguntar "esta string contém aquele texto e onde está?".

Este capítulo aborda a sintaxe, a importantíssima verificação com === false, o parâmetro $offset, a diferenciação entre maiúsculas e minúsculas, e as funções relacionadas que você deve conhecer.

Sintaxe

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

Valor de retorno: a posição inteira da primeira correspondência (contando a partir de 0), ou false quando $needle não for encontrado.

Exemplo básico

"World" começa no índice 6 em "Hello World" (o H está no índice 0), então a saída é:

Found 'World' in 'Hello World' at position 6

O problema do === false (leia isto)

Este é o bug mais comum com strpos(). Quando a correspondência está no início da string, strpos() retorna 0 — e 0 é falso no PHP. Se você testar o resultado com uma verificação solta como if (!strpos(...)) ou if (strpos(...) == false), uma correspondência válida na posição 0 é confundida com "não encontrado".

<?php

$haystack = "php is great";

// WRONG: 0 is treated as "not found"
if (strpos($haystack, "php")) {
  echo "loose: found\n";
} else {
  echo "loose: not found (WRONG!)\n";
}

// RIGHT: use the strict !== operator
if (strpos($haystack, "php") !== false) {
  echo "strict: found\n";
} else {
  echo "strict: not found\n";
}

Saída:

loose: not found (WRONG!)
strict: found

Sempre compare o resultado com o operador estrito !== (ou ===). Esta é a regra de ouro do strpos().

Pesquisando a partir de um offset

O terceiro argumento indica ao strpos() onde começar. É assim que você encontra a segunda (e posteriores) ocorrências de uma substring — encontre a primeira e, em seguida, pesquise novamente começando logo após ela.

<?php

$text = "cat, dog, cat, bird";

$first  = strpos($text, "cat");        // 0
$second = strpos($text, "cat", $first + 1); // 10

echo "first: $first\n";
echo "second: $second\n";

Saída:

first: 0
second: 10

Um offset negativo inicia a pesquisa esse número de caracteres a partir do final da string.

Diferenciação entre maiúsculas e minúsculas

strpos() diferencia maiúsculas de minúsculas: "World" e "world" são substrings diferentes.

<?php

var_dump(strpos("Hello World", "world")); // bool(false)
var_dump(strpos("Hello World", "World")); // int(6)

Se você precisar de uma pesquisa sem diferenciação entre maiúsculas e minúsculas, use stripos() — ela tem a mesma assinatura, mas ignora a distinção entre maiúsculas e minúsculas.

Apenas verificando "ela contém X?"

Se você só quer saber se uma substring existe (não onde), o PHP 8.0+ oferece a função muito mais clara str_contains(), que retorna um boolean simples e evita completamente o problema do === false:

<?php

// PHP 8.0+
var_dump(str_contains("Hello World", "World")); // bool(true)
var_dump(str_contains("Hello World", "world")); // bool(false)

Use strpos() quando precisar da posição; use str_contains() quando precisar apenas de uma resposta sim/não.

Funções relacionadas

• stripos() — versão sem diferenciação de maiúsculas e minúsculas do strpos().
• strrpos() — encontra a última ocorrência em vez da primeira.
• strstr() — retorna a parte da string a partir da primeira correspondência.
• substr() — extrai uma fatia quando você já conhece a posição.
• str_replace() — substitui todas as ocorrências de uma substring.
• preg_match() — pesquisa baseada em padrões quando você precisa de expressões regulares.

Conclusão

strpos() retorna a posição baseada em zero da primeira ocorrência de uma substring, ou false se ela estiver ausente. Lembre-se das duas regras que mais confundem as pessoas: sempre teste o resultado com o estrito !== false, e recorra a stripos() ou str_contains() quando precisar de pesquisa sem diferenciação de maiúsculas e minúsculas ou de uma simples verificação boolean.

Prática