str_replace e str_ireplace en PHP: reemplazar texto sin sorpresas

str_replace() sustituye todas las apariciones de una cadena dentro de otra. Es la función de reemplazo de texto más usada en PHP: está en cualquier proyecto que limpie HTML, genere slugs o prepare datos antes de guardarlos en base de datos. Su variante str_ireplace() hace exactamente lo mismo pero sin distinguir mayúsculas de minúsculas.

Sintaxis básica

<?php
str_replace(
    array|string $search,
    array|string $replace,
    string|array $subject,
    int          &$count = null
): string|array
?>

$search es lo que buscas, $replace lo que pones en su lugar y $subject la cadena (o array de cadenas) sobre la que actúas. El cuarto parámetro $count es opcional y recibirá el número total de sustituciones realizadas.

Reemplazo simple

<?php
$plantilla = 'Hola, {{nombre}}. Tu pedido {{pedido}} está listo.';

$mensaje = str_replace(
    ['{{nombre}}', '{{pedido}}'],
    ['María',      'PED-000742'],
    $plantilla
);

echo $mensaje;
// Hola, María. Tu pedido PED-000742 está listo.
?>

Cuando $search y $replace son arrays, PHP los empareja por posición. Si $replace tiene menos elementos que $search, el sobrante se reemplaza con una cadena vacía, lo que equivale a eliminarlo.

Diferencia entre str_replace y str_ireplace

str_ireplace() realiza la búsqueda sin distinguir mayúsculas de minúsculas. La cadena devuelta mantiene el casing original del texto, solo cambia la parte sustituida:

<?php
$comentario = 'Este producto es BUENISIMO, me parece buenisimo de verdad.';

// str_replace solo encuentra coincidencias exactas
echo str_replace('buenisimo', '***', $comentario);
// "Este producto es BUENISIMO, me parece *** de verdad."

// str_ireplace ignora mayúsculas
echo str_ireplace('buenisimo', '***', $comentario);
// "Este producto es ***, me parece *** de verdad."
?>

Contar cuántas sustituciones se hicieron

El cuarto parámetro recibe el recuento por referencia. Sirve para auditar el resultado o para actuar solo si hubo cambios:

<?php
$texto  = 'El gato y el perro son animales. El gato duerme mucho.';
$count  = 0;

$nuevo  = str_replace('gato', 'felino', $texto, $count);

echo $nuevo . "n";
// "El felino y el perro son animales. El felino duerme mucho."

echo "Sustituciones realizadas: $countn";
// Sustituciones realizadas: 2

if ($count > 0) {
    // guardar $nuevo en base de datos
}
?>

Sustituir sobre un array de cadenas

Cuando el tercer argumento es un array, str_replace() aplica la misma sustitución a todos los elementos y devuelve un nuevo array:

<?php
$titulos = [
    'Introducción a PHP',
    'PHP avanzado: traits y generadores',
    'Seguridad en PHP moderno',
];

$limpios = str_replace('PHP', 'Python', $titulos);

print_r($limpios);
// Array ( [0] => Introducción a Python [1] => Python avanzado: traits y generadores [2] => Seguridad en Python moderno )
?>

Cuándo usar preg_replace en lugar de str_replace

str_replace() busca cadenas literales exactas. En cuanto necesitas patrones (eliminar todos los dígitos, reemplazar múltiples espacios, normalizar saltos de línea) es mejor opción preg_replace():

<?php
$entrada = "  texto   con    espacios   extra  ";

// str_replace no ayuda aquí porque no conoce las expresiones regulares
$limpio = preg_replace('/s+/', ' ', trim($entrada));
echo $limpio; // "texto con espacios extra"
?>

La documentación oficial de str_replace() incluye notas sobre el orden en que se aplican las sustituciones cuando se usan arrays, lo que puede generar resultados inesperados si los patrones se solapan.