substr_replace()

Introducción

La función substr_replace() reemplaza parte de una cadena con otra cadena, basándose en una posición numérica en lugar de un patrón de búsqueda. Le indicas dónde comenzar y cuántos caracteres sobrescribir, y la función inserta el reemplazo en ese lugar. Esto la hace ideal para ediciones en posiciones fijas — enmascarar los dígitos de una tarjeta de crédito, reemplazar una porción de una fecha o insertar texto en un desplazamiento conocido.

Esto es diferente de str_replace(), que busca y reemplaza mediante la coincidencia de una subcadena. Usa substr_replace() cuando conozcas la posición; usa str_replace() cuando conozcas el valor.

Sintaxis

substr_replace(
    array|string $string,
    array|string $replace,
    array|int $offset,
    array|int|null $length = null
): string|array

La función devuelve la cadena resultante. No modifica $string en su lugar — debes capturar el valor de retorno.

Ejemplo básico

Comenzando en el índice 7 (w), se eliminan cinco caracteres y "universe" se inserta en su lugar.

Insertar sin eliminar

Pasa 0 como longitud y no se elimina nada — el reemplazo simplemente se inserta antes del desplazamiento.

<?php

echo substr_replace("Hello", "ABC", 2, 0); // HeABCllo

Reemplazar desde un desplazamiento negativo

Un $offset negativo cuenta hacia atrás desde el final de la cadena, lo que es útil cuando no conoces la longitud de antemano.

<?php

echo substr_replace("Hello", "X", -1);     // HellX  (replace the last character)
echo "\n";
echo substr_replace("12345", "X", 1, -1);  // 1X5    (replace from index 1 to 1-before-the-end)

Un ejemplo práctico: enmascarar dígitos

Sobrescribir una porción conocida con el mismo número de caracteres * es un uso común en el mundo real — por ejemplo, ocultar parte de un número de tarjeta.

<?php

$card = "4111111111111111";
echo substr_replace($card, "********", 4, 8); // 4111********1111

Uso con arrays

Si pasas un array de cadenas, substr_replace() aplica el reemplazo a cada elemento y devuelve un nuevo array. También puedes pasar arrays para $replace, $offset y $length para usar valores diferentes por elemento.

<?php

$names = ["Alice", "Bob", "Carol"];
$result = substr_replace($names, "***", 1, 2);
print_r($result);
// Array
// (
//     [0] => A***ce
//     [1] => B***
//     [2] => C***ol
// )

Errores comunes

• Devuelve una nueva cadena. substr_replace($s, ...) solo no hace nada visible — asigna o muestra el resultado.
• Los desplazamientos son posiciones de bytes, no de caracteres. Para texto multibyte (UTF-8) no existe mb_substr_replace; calcula los desplazamientos con cuidado o reconstruye la cadena con mb_substr().
• Un desplazamiento más allá del final de la cadena agrega el reemplazo en lugar de sobrescribir.

Funciones relacionadas

• str_replace() — reemplazar coincidiendo un valor en lugar de una posición.
• substr() — extraer una porción de una cadena.
• strpos() — encontrar la posición para usar con substr_replace().
• str_pad() — rellenar una cadena hasta una longitud dada.

Conclusión

substr_replace() es la contraparte basada en posición de str_replace(). Una vez que recuerdas que el desplazamiento y la longitud describen un segmento — y que una longitud de 0 inserta mientras que un desplazamiento negativo cuenta desde el final — se convierte en una herramienta precisa para enmascarar, empalmar y editar cadenas en posiciones conocidas.

Práctica