PHP substr_replace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
String

Definition

In PHP, substr_replace() replaces a part of a string with new text.

You choose where to start and how many characters to replace. A length of 0 inserts text instead.

Syntax

Call substr_replace() with the values you need. Start with this line.

PHP
$new = substr_replace($text, "PHP", 6, 5);
CallWhat it does
substr_replace("Hello World", "PHP", 6, 5)Returns "Hello PHP".
substr_replace("Hello World", "Big ", 6, 0)Inserts text. Returns "Hello Big World".
substr_replace("Hello", "!", -1, 0)Adds a character before the last one.

It can also work on arrays of strings. Then offset and length may be arrays, too.

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

Parameters

ParameterDescription
stringRequired. The input string or array of strings.
replaceRequired. The text to put in.
offsetRequired. Where replacement starts. A negative value counts from the end.
lengthOptional. How many characters to replace. 0 means insert. If omitted, replaces to the end.

Return Value

Return ValueDescription
stringThe new string when the input is a string.
arrayAn array of new strings when the input is an array.

PHP Examples

Example 1 — Replace Part of a String

Swap "World" for "PHP".

PHP
<?php
$text = "Hello World";
$new = substr_replace($text, "PHP", 6, 5);

echo $new, PHP_EOL;

How It Works

  1. Start at 6. That is where "World" begins.
  2. Replace 5 characters. "World" has five letters.
  3. Insert new text. "PHP" takes their place.
  4. Print. You get Hello PHP.

Example 2 — Insert With a Length of 0

If length is 0, nothing is removed and the new text is inserted at the offset.

PHP
<?php
$text = "Hello World";

echo substr_replace($text, "Big ", 6, 0), PHP_EOL;
echo substr_replace($text, "Say: ", 0, 0), PHP_EOL;

How It Works

  1. Length 0. No characters are removed.
  2. Insert in the middle. "Big " goes at position 6.
  3. Insert at the start. Offset 0 adds text to the front.
  4. Same function. One tool does replace and insert.

Example 3 — Mask a Card Number

Hide the first 12 digits and show only the last 4.

PHP
<?php
$card = "1234567812345678";
$masked = substr_replace($card, str_repeat("*", 12), 0, 12);

echo $masked, PHP_EOL;

How It Works

  1. Build the mask. str_repeat("*", 12) makes 12 stars.
  2. Replace the start. Offset 0 and length 12 cover the first 12 digits.
  3. Keep the end. The last four digits are untouched.
  4. Print. You see the stars followed by 5678.

Frequently Asked Questions

substr_replace() replaces a section of a string, defined by an offset and length, with new text.
substr_replace(array|string $string, array|string $replace, array|int $offset, array|int|null $length = null). The first three arguments are required.
Use a length of 0. The text is added at the offset and nothing is replaced.
No. It returns a new string. Assign it to a variable to keep it.
substr_replace() works by position. str_replace() searches for matching text and replaces it wherever it appears.

Next: trim()

trim() removes whitespace or other characters from the start and end of a string.

trim() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful