str_ireplace()

A função str_ireplace() no PHP substitui todas as ocorrências de uma string de busca por uma string de substituição, ignorando maiúsculas e minúsculas. É a versão sem distinção de maiúsculas/minúsculas de str_replace(): tudo funciona da mesma forma, exceto que a busca não é sensível a letras maiúsculas e minúsculas. Isso torna str_ireplace() a escolha certa quando a capitalização do texto-alvo é desconhecida ou inconsistente — por exemplo, ao limpar entradas de usuário ou normalizar tags que podem aparecer como PHP, php ou Php.

Este artigo aborda a sintaxe de str_ireplace(), como cada parâmetro se comporta, como trabalhar com arrays, como contar substituições e os pontos de atenção a se observar.

Sintaxe

str_ireplace(
    array|string $search,
    array|string $replace,
    string|array $subject,
    int &$count = null
): string|array

A função recebe três parâmetros obrigatórios e um opcional:

• $search — o valor (ou array de valores) a ser procurado.
• $replace — o valor (ou array de valores) pelo qual substituir.
• $subject — a string (ou array de strings) onde realizar a busca.
• $count (opcional) — uma variável passada por referência que é preenchida com o número total de substituições realizadas.

Retorna o $subject modificado. Se $subject for um array, é retornado um array com a substituição aplicada a cada elemento.

Exemplo básico

Mesmo buscando por "FOX" em maiúsculas, str_ireplace() ignora a capitalização e encontra o "fox" minúsculo no sujeito. A saída é:

The quick brown cat jumps over the lazy dog

Com o str_replace() padrão, sensível a maiúsculas/minúsculas, a mesma chamada não encontraria correspondência e a string seria retornada sem alterações.

Usando arrays para busca e substituição

Quando $search e $replace são ambos arrays, cada valor de busca é pareado com a substituição no mesmo índice. Isso permite realizar várias substituições em uma única chamada:

<?php
$search  = ["red", "GREEN", "Blue"];
$replace = ["crimson", "emerald", "navy"];
$subject = "Red, green and blue are colors.";

echo str_ireplace($search, $replace, $subject);
// crimson, emerald and navy are colors.
?>

Note que a capitalização das entradas em $search não importa — "GREEN" ainda corresponde a "green". Se $replace tiver menos elementos do que $search, as substituições faltantes são tratadas como strings vazias (as correspondências são removidas).

Quando $search é um array, mas $replace é uma única string, essa string substitui todos os valores de busca:

<?php
echo str_ireplace(["cats", "dogs"], "pets", "I have CATS and Dogs.");
// I have pets and pets.
?>

Contando substituições com $count

Passe um quarto argumento por referência para saber quantas substituições foram feitas:

<?php
$text   = "PHP is great. php is fun. PhP rocks.";
$result = str_ireplace("php", "PHP", $text, $count);

echo $result . "\n";       // PHP is great. PHP is fun. PHP rocks.
echo "Replacements: $count"; // Replacements: 3
?>

As três variantes PHP, php e PhP são todas encontradas, portanto $count é 3. Isso é útil para validação — por exemplo, verificar se uma palavra proibida apareceu.

Pontos de atenção

• A substituição não é buscada novamente. str_ireplace() processa os termos de busca da esquerda para a direita e nunca reescaneia o texto já inserido, portanto não pode entrar em loop infinito. Mas a ordem ainda importa quando um termo de busca é uma substring de outro.
• Opera em bytes, não em caracteres multibyte. Para texto UTF-8 onde a insensibilidade a maiúsculas/minúsculas deve respeitar letras acentuadas ou não latinas, str_ireplace() pode não se comportar como esperado. Use as funções mb_* do PHP ou preg_replace() com o modificador i.
• Use str_replace() quando a capitalização importa. Se você precisa de correspondência exata e sensível a maiúsculas/minúsculas, use str_replace() — é ligeiramente mais rápido pois ignora a etapa de normalização de capitalização.

Resumo

str_ireplace() realiza busca e substituição sem distinção de maiúsculas/minúsculas em strings. Use-a para substituições literais simples onde a capitalização deve ser ignorada; use str_replace() quando a capitalização importa, e preg_replace() quando você precisar de correspondência baseada em padrões ou com suporte a multibyte.

Prática