str_ireplace()

La función str_ireplace() en PHP reemplaza todas las ocurrencias de una cadena de búsqueda por una cadena de reemplazo, ignorando las mayúsculas y minúsculas. Es la versión sin distinción de mayúsculas/minúsculas de str_replace(): todo funciona de la misma manera, excepto que la búsqueda no distingue entre letras mayúsculas y minúsculas. Esto convierte a str_ireplace() en la opción adecuada cuando no se conoce el formato exacto del texto objetivo o es inconsistente — por ejemplo, al limpiar entradas del usuario o normalizar etiquetas que pueden aparecer como PHP, php o Php.

Este artículo cubre la sintaxis de str_ireplace(), cómo se comporta cada parámetro, cómo trabajar con arrays, cómo contar los reemplazos y los aspectos a tener en cuenta.

Sintaxis

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

La función acepta tres parámetros obligatorios y uno opcional:

• $search — el valor (o array de valores) que se buscará.
• $replace — el valor (o array de valores) con el que se reemplazará.
• $subject — la cadena (o array de cadenas) en la que buscar.
• $count (opcional) — una variable pasada por referencia que se rellena con el número total de reemplazos realizados.

Devuelve el $subject modificado. Si $subject es un array, se devuelve un array con el reemplazo aplicado a cada elemento.

Ejemplo básico

Aunque buscamos "FOX" en mayúsculas, str_ireplace() ignora las mayúsculas y coincide con el "fox" en minúsculas del sujeto. La salida es:

The quick brown cat jumps over the lazy dog

Con la función estándar str_replace(), que distingue entre mayúsculas y minúsculas, la misma llamada no encontraría ninguna coincidencia y la cadena se devolvería sin cambios.

Uso de arrays para búsqueda y reemplazo

Cuando $search y $replace son ambos arrays, cada valor de búsqueda se empareja con el reemplazo en el mismo índice. Esto permite realizar varias sustituciones en una sola llamada:

<?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.
?>

Observe que el formato de las entradas en $search no importa — "GREEN" sigue coincidiendo con "green". Si $replace tiene menos elementos que $search, los reemplazos faltantes se tratan como cadenas vacías (las coincidencias se eliminan).

Cuando $search es un array pero $replace es una sola cadena, esa cadena reemplaza todos los valores de búsqueda:

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

Conteo de reemplazos con $count

Pase un cuarto argumento por referencia para saber cuántos reemplazos se realizaron:

<?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
?>

Las tres variantes PHP, php y PhP se detectan todas, por lo que $count es 3. Esto es útil para validación — por ejemplo, para comprobar si una palabra prohibida apareció en algún momento.

Aspectos a tener en cuenta

• El reemplazo no se vuelve a buscar. str_ireplace() procesa los términos de búsqueda de izquierda a derecha y nunca re-escanea el texto que ya ha insertado, por lo que no puede entrar en bucle infinito. Pero el orden sigue importando cuando un término de búsqueda es una subcadena de otro.
• Opera sobre bytes, no sobre caracteres multibyte. Para texto UTF-8 donde la insensibilidad a mayúsculas/minúsculas debe respetar letras acentuadas o no latinas, str_ireplace() puede no comportarse como se espera. Use las funciones de cadena mb_* de PHP o preg_replace() con el modificador i en su lugar.
• Use str_replace() cuando las mayúsculas importan. Si necesita una coincidencia exacta con distinción de mayúsculas/minúsculas, use str_replace() — es ligeramente más rápido porque omite el paso de normalización de mayúsculas.

Resumen

str_ireplace() realiza búsqueda y reemplazo sin distinción de mayúsculas/minúsculas en cadenas. Úselo para sustituciones simples y literales donde las mayúsculas deben ignorarse; use str_replace() cuando las mayúsculas importen, y preg_replace() cuando necesite coincidencias basadas en patrones o con soporte multibyte.

Práctica