Sustituir un fragmento literal en PHP con str_replace

Reemplazo literal de todas las apariciones

str_replace busca un texto literal, distingue mayúsculas y no interpreta expresiones regulares. Devuelve el texto modificado; la cadena original permanece igual si no reasignas el resultado.

$original = 'ruta/vieja y ruta/vieja';
$nueva = str_replace('ruta/vieja', 'ruta/nueva', $original, $cambios);
echo $nueva, PHP_EOL; // ruta/nueva y ruta/nueva
echo $cambios, PHP_EOL; // 2
echo $original, PHP_EOL; // ruta/vieja y ruta/vieja

El contador permite diferenciar una transformación que encontró coincidencias de otra que recibió un formato inesperado. No garantiza que el nuevo texto sea correcto para otro lenguaje: una ruta, una etiqueta HTML y un documento JSON requieren reglas distintas.

Una sustitución o varias

Para reemplazar un fragmento en una posición conocida puedes utilizar substr_replace. Para reemplazar sólo la primera aparición literal, localiza la posición con strpos, comprueba !== false y sustituye la longitud exacta. Si la coincidencia está al principio, su posición será cero y no debe confundirse con un fallo.

$texto = 'rojo, rojo';
$pos = strpos($texto, 'rojo');
if ($pos !== false) {
    $texto = substr_replace($texto, 'azul', $pos, strlen('rojo'));
}
echo $texto, PHP_EOL; // azul, rojo

Texto, rutas y caracteres

Las funciones de longitud y posición anteriores trabajan con bytes. En el ejemplo, la longitud se calcula a partir del mismo fragmento encontrado, por lo que sustituye sus bytes completos. Si estás cortando por posiciones de caracteres en textos Unicode, elige las funciones multibyte adecuadas.

No modifiques un documento estructurado mediante reemplazos indiscriminados: cambiar una palabra en un JSON crudo puede alterar claves además de valores. Decodifica, cambia el campo previsto y vuelve a codificar. Para decidir entre sustitución literal y patrones, continúa con la comparación de funciones enlazada abajo.

Referencia 1

Referencia 2