str_replace en PHP: cómo reemplazar texto

str_replace sirve para reemplazar texto dentro de una cadena en PHP. Busca una cadena de forma literal y la sustituye por otra en todas sus apariciones. Distingue entre mayúsculas y minúsculas y no interpreta patrones ni expresiones regulares: para eso existe preg_replace.

Sintaxis de str_replace

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

• $search: texto (o array de textos) que quieres encontrar.
• $replace: texto (o array de textos) que se pondrá en su lugar.
• $subject: texto (o array de textos) donde se hacen los reemplazos.
• $count: parámetro opcional que se pasa por referencia y donde PHP guarda cuántos reemplazos se han hecho.

La función devuelve un string o un array según el tipo de $subject.

Ejemplo básico

<?php
$texto = 'Hola, mundo';
$texto = str_replace('mundo', 'PHP', $texto);

echo $texto; // Hola, PHP

Reemplazar varias cadenas con arrays

Puedes pasar arrays como búsqueda y reemplazo:

<?php
$texto = 'Hola, mundo';
$texto = str_replace(['Hola', 'mundo'], ['Adiós', 'PHP'], $texto);

echo $texto; // Adiós, PHP

Cada búsqueda usa la sustitución que ocupa su misma posición en el array de reemplazos. Si faltan elementos en $replace, los valores sin reemplazo equivalente se sustituyen por una cadena vacía. Si $replace es una cadena, esa misma cadena se usa para todas las búsquedas. Además, $subject también puede ser un array, y en ese caso la función devuelve un array con el mismo esquema.

Contar cuántos reemplazos se han hecho

El cuarto argumento se rellena por referencia: PHP escribe en él el número de reemplazos realizados.

<?php
$texto = 'mundo, mundo, mundo';
$conteo = 0;

$texto = str_replace('mundo', 'PHP', $texto, $conteo);

echo $conteo; // 3

Diferencia entre str_replace y str_ireplace

str_replace distingue entre mayúsculas y minúsculas. Si necesitas ignorarlas, usa str_ireplace.

<?php
echo str_replace('php', 'PHP', 'Me gusta Php'); // No cambia nada
echo str_ireplace('php', 'PHP', 'Me gusta Php'); // Me gusta PHP

Desde PHP 8.2, el case folding de str_ireplace se limita a ASCII; no elimina acentos ni ofrece un case folding Unicode completo, y los bytes no ASCII se comparan tal cual.

Orden de los reemplazos

Las búsquedas se procesan de izquierda a derecha, no todas a la vez. Eso significa que una sustitución ya insertada puede volver a coincidir con una búsqueda posterior:

<?php
echo str_replace(
    ['A', 'B'],
    ['B', 'C'],
    'A'
); // C

Primero A se convierte en B y después esa B coincide con la segunda búsqueda, así que el resultado final es C.

Cuándo usar preg_replace

str_replace es la opción adecuada para reemplazos de texto literal. Cuando la búsqueda necesita un patrón (por ejemplo, espacios repetidos, dígitos o etiquetas), usa preg_replace:

<?php
$texto = preg_replace('/\s+/', ' ', $texto);

preg_replace puede devolver null si el patrón produce un error, así que conviene comprobar el resultado cuando el patrón no es fijo.

Detalles importantes

• str_replace es binary-safe: trabaja con bytes, así que no modifica la codificación del texto.
• No existe str_replace_once; si necesitas limitar el número de reemplazos, preg_replace admite un parámetro $limit.

$texto = 'Hola y Hola';
$resultado = preg_replace('/Hola/', 'Adiós', $texto, 1);
echo $resultado; // Adiós y Hola

/Hola/ es un patrón delimitado de expresión regular PCRE aunque busque texto sencillo, y 1 limita el reemplazo a la primera coincidencia. preg_replace no es una búsqueda literal idéntica a str_replace.