stristr()

Introdução

stristr() é uma função de string do PHP que encontra a primeira ocorrência de uma substring dentro de uma string, ignorando diferença entre maiúsculas e minúsculas, e retorna tudo a partir desse ponto até o final da string. Se a substring não for encontrada, retorna false.

É a versão sem distinção de maiúsculas/minúsculas de strstr(). Use stristr() quando a correspondência deve tratar Hello, HELLO e hello como iguais — por exemplo, ao pesquisar palavras-chave digitadas pelo usuário, analisar um endereço de e-mail ou dividir uma string em um marcador independentemente do caso.

Esta página aborda a sintaxe, o valor de retorno, o parâmetro opcional $before_needle, armadilhas comuns e como stristr() difere de funções relacionadas.

Sintaxe

stristr(string $haystack, string $needle, bool $before_needle = false): string|false

Valor de retorno: a porção correspondente de $haystack (a capitalização original é preservada, sem conversão para minúsculas), ou false se $needle não aparecer.

Exemplo básico

Mesmo pesquisando por "BROWN" em maiúsculas, stristr() correspondeu ao brown em minúsculas na string e retornou o restante da frase a partir dessa palavra — com a capitalização original intacta.

Obtendo a parte antes da correspondência

Passe true como terceiro argumento para retornar tudo antes da primeira correspondência. Isso é útil para dividir uma string em um delimitador, como extrair a parte do usuário de um endereço de e-mail:

<?php

$email = "[email protected]";

$after  = stristr($email, "@");        // from "@" onward
$before = stristr($email, "@", true);  // up to (not including) "@"

echo $after . "\n";   // @Example.com
echo $before . "\n";  // User

Verificando se uma substring existe

Um erro comum é usar stristr() como teste booleano. Funciona, mas você deve comparar com false usando o operador estrito !==, pois a string retornada pode ser falsa por si mesma (por exemplo, "0"):

<?php

$text = "Contact us at [email protected]";

if (stristr($text, "support") !== false) {
  echo "Contains 'support' (any case)";
} else {
  echo "Not found";
}
// Output: Contains 'support' (any case)

Se você só precisa saber se uma substring existe — e não precisa da porção correspondida — prefira stripos() (posição sem distinção de maiúsculas/minúsculas) ou strpos() (sensível a maiúsculas/minúsculas). Elas retornam o índice da correspondência e são ligeiramente mais rápidas porque não copiam o restante da string.

stristr() vs. funções relacionadas

Use stristr() quando quiser o texto a partir da correspondência e o caso deve ser ignorado. Use stripos()/strpos() quando precisar apenas da posição ou de uma resposta sim/não.

Observações e armadilhas

• false vs. string vazia. Uma correspondência bem-sucedida nunca retorna uma string vazia no início, mas uma correspondência no final de $haystack retorna apenas o needle. Sempre teste com !== false.
• O caso é ignorado apenas para correspondência. A substring retornada mantém a capitalização do $haystack original.
• Texto multibyte/UTF-8. stristr() opera em bytes. Para correspondência confiável sem distinção de maiúsculas/minúsculas de caracteres acentuados ou não latinos, use mb_stristr() da extensão mbstring.
• $needle não-string. A partir do PHP 8.0, $needle é sempre tratado como string. Em versões mais antigas, um needle não-string era interpretado como seu código de caractere ASCII.

Conclusão

stristr() retorna a porção de uma string a partir da primeira correspondência sem distinção de maiúsculas/minúsculas de uma substring, ou false quando não há correspondência — e com $before_needle definido como true, a porção antes da correspondência. Escolha-a quando precisar do texto correspondido independentemente do caso; escolha stripos() ou strpos() quando precisar apenas de uma posição ou verificação de presença.

Prática