PHP str_replace(): reemplazar texto en un string

str_replace($search, $replace, $subject) devuelve una copia de $subject con cada aparición de $search sustituida por $replace. str_replace('world', 'PHP', 'Hello world') devuelve "Hello PHP".

<?php
$text = 'I like cats. cats are great.';

$new = str_replace('cats', 'dogs', $text);

echo $new, "\n";
echo $text, "\n";   // the original is unchanged

La función devuelve la cadena nueva; no modifica la variable que le pasas. Asigna el resultado, aunque sea a la misma variable: $text = str_replace(...).

Sintaxis

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

Cada uno de los tres primeros argumentos puede ser una cadena o un array. Si $subject es un array, el reemplazo se aplica a cada elemento y obtienes un array con las mismas claves: str_replace('.txt', '.md', ['a.txt', 'b.txt']) devuelve ['a.md', 'b.md']. La búsqueda distingue mayúsculas y minúsculas y compara texto literal, no patrones. Para patrones usa preg_replace().

Reemplazar varias cadenas a la vez

Pasa arrays en $search y $replace. El primer valor de búsqueda se sustituye por el primer reemplazo, el segundo por el segundo, y así sucesivamente. Si $replace es una sola cadena, todos los valores de búsqueda se sustituyen por ella, que es la forma corta de eliminar un conjunto de caracteres.

<?php
$template = 'Hello {name}, your order {id} has shipped.';

echo str_replace(['{name}', '{id}'], ['Ada', '#1042'], $template), "\n";

// One replacement for every search value: remove punctuation
echo str_replace(['.', ',', '!', '?'], '', 'Hi, there! Ready? Yes.'), "\n";

// Fewer replacements than searches: the missing ones are ""
echo str_replace(['a', 'b', 'c'], ['1'], 'abcabc'), "\n";

La trampa del orden y strtr()

Con arrays, str_replace() aplica un reemplazo tras otro sobre toda la cadena. Una búsqueda posterior puede coincidir con texto que un reemplazo anterior acaba de insertar. strtr() con un array lo reemplaza todo en una sola pasada, prueba primero las claves más largas y nunca toca texto que ya ha reemplazado.

<?php
$s = 'apple banana';

// apple -> banana, then every banana (including the new one) -> cherry
echo str_replace(['apple', 'banana'], ['banana', 'cherry'], $s), "\n";

// One pass: each original word is replaced once
echo strtr($s, ['apple' => 'banana', 'banana' => 'cherry']), "\n";

Usa strtr() para intercambios y para marcadores de plantilla que puedan aparecer en los valores.

Contar los reemplazos

El cuarto argumento se rellena con el número de reemplazos hechos. Pasa una variable; PHP escribe en ella.

<?php
$text = 'one fish, two fish, red fish, blue fish';

$result = str_replace('fish', 'cat', $text, $count);

echo $result, "\n";
echo "Replaced $count times\n";

Reemplazar sin distinguir mayúsculas con str_ireplace

str_ireplace() acepta los mismos argumentos e ignora las mayúsculas al buscar. El reemplazo se inserta exactamente como lo escribiste.

<?php
$text = 'PHP, php and Php';

echo str_replace('php', 'Python', $text), "\n";
echo str_ireplace('php', 'Python', $text), "\n";

str_ireplace() solo iguala mayúsculas y minúsculas en letras ASCII. Para reemplazar sin distinguir mayúsculas letras con tilde o cirílicas, usa preg_replace() con los modificadores i y u.

Reemplazar solo la primera aparición

str_replace() siempre lo reemplaza todo. Para reemplazar solo la primera coincidencia, encuéntrala con strpos() y córtala con substr_replace():

<?php
function replaceFirst(string $search, string $replace, string $subject): string
{
    $pos = strpos($subject, $search);
    if ($pos === false) {
        return $subject;
    }
    return substr_replace($subject, $replace, $pos, strlen($search));
}

echo replaceFirst('a', 'A', 'banana'), "\n";

// The same with a regex and a limit of 1
echo preg_replace('/' . preg_quote('a', '/') . '/', 'A', 'banana', 1), "\n";

Para la última aparición, usa strrpos() en lugar de strpos().

Quitar espacios, saltos de línea y otros caracteres

Reemplazar por una cadena vacía elimina el texto. Una limpieza habitual quita los saltos de línea o todos los espacios, y la entrada en japonés suele contener espacios de ancho completo (　, U+3000) que una búsqueda normal de " " no encuentra.

<?php
$text = "line one\r\nline two\nline three";
echo str_replace(["\r\n", "\n", "\r"], ' ', $text), "\n";

$phone = '090 1234 5678';
echo str_replace(' ', '', $phone), "\n";

$name = '山田　太郎';
echo str_replace('　', ' ', $name), "\n";   // full-width space to normal space

Pon "\r\n" antes de "\n" y "\r" en el array, para que un salto de línea de Windows se convierta en un espacio y no en dos.