substr_replace()

Introduction

The substr_replace() function replaces part of a string with another string, based on a numeric position rather than a search pattern. You tell it where to start and how many characters to overwrite, and it splices the replacement in. This makes it ideal for fixed-position edits — masking the digits of a credit card, swapping a slice of a date, or inserting text at a known offset.

This is different from str_replace(), which finds and replaces by matching a substring. Use substr_replace() when you know the position; use str_replace() when you know the value.

Syntax

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

The function returns the resulting string. It does not modify $string in place — you must capture the return value.

Basic example

Starting at index 7 (w), five characters are removed and "universe" is dropped in their place.

Inserting without deleting

Pass 0 as the length and nothing is removed — the replacement is simply inserted before the offset.

<?php

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

Replacing from a negative offset

A negative $offset counts back from the end of the string, which is handy when you don't know the length up front.

<?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)

A practical example: masking digits

Overwriting a known slice with the same number of * characters is a common real-world use — for example, hiding part of a card number.

<?php

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

Working with arrays

If you pass an array of strings, substr_replace() applies the replacement to every element and returns a new array. You can also pass arrays for $replace, $offset, and $length to use different values per element.

<?php

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

Common gotchas

• It returns a new string. substr_replace($s, ...) alone does nothing visible — assign or echo the result.
• Offsets are byte positions, not character positions. For multibyte (UTF-8) text there is no mb_substr_replace; compute offsets carefully or rebuild the string with mb_substr().
• An offset past the end of the string appends the replacement rather than overwriting.

Related functions

• str_replace() — replace by matching a value instead of a position.
• substr() — extract a portion of a string.
• strpos() — find the position to feed into substr_replace().
• str_pad() — pad a string to a given length.

Conclusion

substr_replace() is the position-based counterpart to str_replace(). Once you remember that the offset and length describe a slice — and that a length of 0 inserts while a negative offset counts from the end — it becomes a precise tool for masking, splicing, and editing strings at known positions.

Practice