PHP string contains: verifique substring

Para verificar se uma string contém outra em PHP, use str_contains() para testar se uma string inclui outra e obter um resultado booleano. Ela funciona bem em cláusulas de guarda, verificações de roteamento e validação de entrada quando só importa uma resposta de sim ou não. Em comparação com strpos(), evita a armadilha de 0 ser avaliado como falso e mantém o código legível sem !== false. str_contains() está disponível no PHP 8.0+.

Exemplo de PHP string contains para verificar substring

Saída:

Status: enviado

Como este exemplo funciona

1. $message armazena uma string simples com a descrição de status.
2. str_contains($message, "enviado") procura no haystack a substring exata "enviado" e retorna true porque ela aparece na posição 7.
3. O bloco if é executado porque o retorno já é booleano, sem necessidade de comparação com coerção de tipo.

O que é str_contains no PHP?

str_contains(string $haystack, string $needle): bool é uma função do PHP 8.0 que faz uma verificação de substring sensível a maiúsculas/minúsculas e segura em nível de bytes. Ela retorna true quando $needle é encontrado em qualquer parte de $haystack, e false caso contrário. Um $needle vazio sempre retorna true — comportamento definido na especificação do PHP, não um bug.

Erros comuns com str_contains()

Esperar correspondência sem distinguir maiúsculas de minúsculas

Errado:

str_contains("Ola Mundo", "ola"); // false

Certo:

stripos("Ola Mundo", "ola") !== false; // true

str_contains() diferencia maiúsculas de minúsculas. Para buscas sem essa distinção, use stripos() !== false (ou normalize as duas strings antes de chamar str_contains()).

Tratar strpos() como booleano (armadilha de migração)

Errado:

if (strpos("enviado", "env")) echo "corresponde"; // sem saída (0 é avaliado como falso)

Certo:

if (strpos("enviado", "env") !== false) echo "corresponde";

No PHP 8+, prefira str_contains() quando você precisa apenas de um booleano.

str_contains vs strpos vs stripos

Use str_contains() quando você só precisa de uma verificação booleana no PHP 8+. Use strpos() quando precisar da posição da correspondência ou precisar suportar PHP 7.x. Use stripos() para buscas sem diferenciar maiúsculas e minúsculas quando também precisar da posição da correspondência (ele retorna o índice como strpos()).

FAQ

str_contains diferencia maiúsculas de minúsculas?

Sim. str_contains("PHP", "php") retorna false. Para verificações sem diferenciar maiúsculas de minúsculas, converta os dois argumentos para minúsculas com strtolower() antes de chamar str_contains(), ou use stripos($haystack, $needle) !== false.

Por que str_contains retorna true para uma string vazia?

Por definição, a string vazia é uma substring de qualquer string. Isso corresponde ao comportamento de strpos("anything", ""), que retorna 0 no PHP 8. Faça validação de entrada vazia antes de chamar str_contains() se isso puder causar lógica incorreta no seu código.

Como verificar se uma string contém substring no PHP 7?

Use strpos($haystack, $needle) !== false. A comparação estrita !== false é essencial porque strpos() retorna 0 quando o needle está no início, e 0 é avaliado como falso em PHP. Essa armadilha é o principal motivo de str_contains() ter sido introduzido.