Verificação de palavra em string PHP: o que está por baixo do capô?

Introdução: a pergunta que todo desenvolvedor PHP já fez

Imagine a situação: você está programando em PHP e precisa verificar se uma string contém uma determinada palavra. Parece simples, certo? No entanto, ao dar uma olhada no Stack Overflow, você vê que essa pergunta já acumulou milhares de visualizações e dezenas de respostas. As pessoas se confundem com o strpos, usam preg_match quando uma função simples bastaria, e caem em armadilhas com maiúsculas/minúsculas e codificação. Hoje não vamos apenas dar a resposta pronta — vamos mergulhar nos bastidores do PHP e entender como essas funções realmente funcionam. Preparado? Vamos nessa!

O método clássico: strpos e suas armadilhas

A resposta mais popular no Stack Overflow é usar strpos. Esta é uma função nativa do PHP que encontra a posição da primeira ocorrência de uma substring. Mas tem um detalhe: iniciantes geralmente escrevem assim:

$string = "Olá, mundo!";\n$word = "mundo";\nif (strpos($string, $word)) {\n    echo "Palavra encontrada!";\n} else {\n    echo "Palavra não encontrada!";\n}\n

E isso funciona... até que a palavra esteja no início da string. Por quê? Porque strpos retorna a posição (um número), e se a palavra estiver na posição 0, o PHP interpreta 0 como false na condição if. A forma correta é:

if (strpos($string, $word) !== false) {\n    echo "Palavra encontrada!";\n}\n

Como o strpos funciona por baixo dos panos?

Quando você chama strpos, o PHP internamente usa um algoritmo de busca de substring. Nas versões modernas do PHP (7.x e 8.x), é aplicado um algoritmo otimizado baseado no algoritmo de Boyer-Moore-Horspool. Ele não apenas percorre os caracteres um por um, mas usa uma tabela de "caracteres ruins" para pular blocos inteiros de texto se o caractere da palavra pesquisada não coincidir. Isso torna a busca muito rápida, especialmente para strings longas.

Mas há uma limitação: strpos diferencia maiúsculas de minúsculas. "Mundo" e "mundo" são palavras diferentes para ele. Se você precisar de uma verificação que ignore maiúsculas/minúsculas, use stripos — o equivalente que ignora o caso.

O método moderno: str_contains (PHP 8.0+)

A partir do PHP 8.0, foi introduzida a tão esperada função str_contains. Ela resolve o problema do strpos de uma vez por todas. Em vez de verificar a posição, ela simplesmente retorna true ou false:

$string = "Olá, mundo!";\n$word = "mundo";\nif (str_contains($string, $word)) {\n    echo "Palavra encontrada!";\n}\n

O que tem dentro do str_contains?

Por baixo dos panos, str_contains é um wrapper para strpos. Ela chama a mesma função de busca interna, mas o resultado é automaticamente convertido para um valor booleano. Isso torna o código mais limpo e seguro. No entanto, se você estiver trabalhando com versões antigas do PHP (7.4 ou inferior), str_contains não estará disponível — você terá que usar strpos com a verificação !== false.

Ferramenta poderosa: expressões regulares com preg_match

Às vezes, você precisa verificar não apenas a presença de uma palavra, mas um grupo inteiro de palavras ou um padrão. É aqui que entra o preg_match. As expressões regulares te dão superpoderes: você pode buscar palavras inteiras (para que "mundo" não corresponda a "mundial"), ignorar maiúsculas/minúsculas, buscar por limites de palavras e muito mais.

$string = "Olá, mundial!";\n$word = "mundo";\nif (preg_match("/\\b" . preg_quote($word, '/') . "\\b/ui", $string)) {\n    echo "Palavra encontrada!";\n} else {\n    echo "Palavra não encontrada!";\n}\n

Aqui, \\b é o limite da palavra, e a flag u ativa o suporte a Unicode (para que letras acentuadas funcionem corretamente). A flag i torna a busca insensível a maiúsculas/minúsculas. A função preg_quote escapa caracteres especiais, caso a palavra contenha algum.