stripos()

Introdução

stripos() encontra a posição da primeira ocorrência de uma substring dentro de uma string, ignorando a diferença entre maiúsculas e minúsculas. Retorna o índice baseado em zero onde a correspondência começa, ou false quando a substring não está presente.

O i no nome significa case-insensitive: "PHP", "php" e "Php" são tratados da mesma forma. Se precisar de uma busca com distinção de maiúsculas e minúsculas, use strpos(). Esta página aborda a sintaxe, o problema crítico do !== false, o parâmetro opcional $offset e como stripos() se relaciona com as demais funções de posição.

Sintaxe

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

Valor de retorno: a posição baseada em zero da primeira correspondência (um int), ou false se $needle não for encontrada.

Um exemplo básico

A needle "fox" está em minúsculas, mas o haystack contém "FOX". Como stripos() ignora maiúsculas e minúsculas, ainda encontra a correspondência e imprime:

Found 'fox' at position 16

Se usar strpos() aqui, o resultado seria false, pois os casos diferem.

O problema do !== false

Este é o bug mais comum com stripos() (e com todas as funções *pos()). Quando uma correspondência é encontrada no início da string, o valor retornado é 0 — e 0 é falsy em PHP. Uma verificação fraca como if (stripos(...)) trataria uma correspondência real como "não encontrado":

<?php

$pos = stripos("Hello world", "hello");

// Wrong: 0 is falsy, so this branch runs even though there IS a match
if ($pos) {
  echo "loose check: found\n";
} else {
  echo "loose check: NOT found (wrong!)\n";
}

// Correct: compare against false with the strict !== operator
if ($pos !== false) {
  echo "strict check: found at position $pos\n";
} else {
  echo "strict check: not found\n";
}

Saída:

loose check: NOT found (wrong!)
strict check: found at position 0

Sempre compare o resultado com !== false quando quiser apenas saber se a substring existe.

Usando o parâmetro $offset

O terceiro argumento permite iniciar a busca em uma posição intermediária da string — útil para encontrar a segunda (ou posterior) ocorrência:

<?php

$text = "PHP is great. PHP is everywhere.";

$first  = stripos($text, "php");        // start at 0
$second = stripos($text, "php", $first + 1); // skip past the first match

echo "First occurrence:  $first\n";
echo "Second occurrence: $second\n";

Saída:

First occurrence:  0
Second occurrence: 14

Um uso prático: filtro de palavras-chave sem distinção de maiúsculas

Por ignorar maiúsculas e minúsculas, stripos() é ideal para verificações do tipo "este texto menciona X?", como sinalizar mensagens que contenham uma palavra proibida independentemente de como foi digitada:

<?php

$message = "Get this AMAZING deal now!";
$banned  = ["amazing", "free", "winner"];

foreach ($banned as $word) {
  if (stripos($message, $word) !== false) {
    echo "Blocked: contains '$word'\n";
    break;
  }
}

Saída:

Blocked: contains 'amazing'

Funções relacionadas

Veja também substr() para extrair texto após obter uma posição, e str_replace() para substituições com distinção de maiúsculas.

Conclusão

stripos() retorna a posição baseada em zero da primeira correspondência sem distinção de maiúsculas e minúsculas de uma substring, ou false se não houver nenhuma. Lembre-se de testar o resultado com !== false para que uma correspondência na posição 0 não seja confundida com "não encontrado", use $offset para encontrar ocorrências posteriores e recorra a strpos() quando o caso importar.

Prática