str_replace()

La función PHP str_replace() reemplaza todas las ocurrencias de una cadena de búsqueda por una cadena de reemplazo. Es útil para encontrar y sustituir patrones específicos dentro de textos más extensos. A continuación, cubrimos la sintaxis, las características principales y ejemplos de uso.

La función str_replace() se utiliza para reemplazar todas las ocurrencias de una cadena dentro de otra cadena. La sintaxis de la función str_replace() es la siguiente:

La sintaxis PHP de str_replace()

str_replace($search, $replace, $subject, $count = null)

La función acepta tres parámetros obligatorios y uno opcional: $search, $replace, $subject y $count.

• $search: La cadena, o array de cadenas, a buscar.
• $replace: La cadena, o array de cadenas, con la que 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 de reemplazos realizados.

La función devuelve el $subject modificado. La cadena original nunca se cambia en su lugar, por lo que debe capturar el valor de retorno. str_replace() distingue entre mayúsculas y minúsculas — "World" y "world" se tratan como cadenas diferentes. Si necesita ignorar la distinción de mayúsculas y minúsculas, use str_ireplace() en su lugar.

Un ejemplo básico

Esta es la forma más sencilla de usar la función str_replace() — reemplazando una palabra por otra:

Ejemplo de PHP str_replace()

En este ejemplo, la variable string $string contiene la frase "The quick brown fox jumps over the lazy dog." Reemplazamos la palabra "brown" por "red" pasando "brown" como $search y "red" como $replace. La salida es:

The quick red fox jumps over the lazy dog.

Cada ocurrencia es reemplazada, no solo la primera. Si la cadena de búsqueda apareciera tres veces, las tres serían sustituidas en una sola llamada.

Reemplazar múltiples cadenas a la vez

Cuando $search y $replace son arrays, cada elemento de $search es reemplazado por el elemento en el mismo índice de $replace. El cuarto argumento opcional, $count, se pasa por referencia y recibe el número total de reemplazos:

Ejemplo con arrays y $count

<?php
$search = ["brown", "fox"];
$replace = ["red", "bear"];
$subject = "The quick brown fox jumps over the lazy dog.";
$count = 0;
$result = str_replace($search, $replace, $subject, $count);
echo $result; // Output: The quick red bear jumps over the lazy dog.
echo "Replacements made: $count"; // Output: Replacements made: 2
?>

Si $replace es una cadena única pero $search es un array, esa cadena se usa para todas las coincidencias:

<?php
$result = str_replace(["a", "e", "i"], "*", "education");
echo $result; // Output: *duc*t*on
?>

Un problema: los reemplazos se encadenan

Los reemplazos de arrays se aplican en orden, y cada uno se ejecuta sobre el resultado del anterior. Esto significa que un valor recién insertado puede ser coincidido de nuevo por un término de búsqueda posterior:

<?php
$count = 0;
$result = str_replace(["A", "B"], ["B", "C"], "A", $count);
echo $result;        // Output: C
echo "\n";
echo "Replacements: $count"; // Output: Replacements: 2
?>

Aquí "A" se convierte en "B" en el primer paso, luego ese "B" se convierte en "C" en el segundo paso — por lo que el resultado final es "C", con dos reemplazos contados. Ordene cuidadosamente sus pares búsqueda/reemplazo para evitar esto, o use strtr() cuando necesite que cada par se aplique exactamente una vez.

Cuándo usar str_replace()

• Use str_replace() para búsquedas y reemplazos literales rápidos cuando conoce el texto exacto.
• Use str_ireplace() cuando la coincidencia deba ignorar mayúsculas y minúsculas.
• Use substr_replace() para reemplazar una parte de una cadena por posición en lugar de por contenido.
• Use preg_replace() cuando necesite coincidencia de patrones con expresiones regulares.

La función str_replace() ofrece una forma sencilla y eficiente de buscar y reemplazar texto en PHP. Como trabaja con cadenas simples sin la sobrecarga de las expresiones regulares, es la herramienta adecuada cuando se trabaja con texto literal exacto.

Práctica