PHP str_replace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
String

Definition

In PHP, str_replace() replaces all occurrences of a search value with a replacement value in a string.

It is case-sensitive, works on strings or arrays, and can report how many replacements it made.

Syntax

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

PHP
$new = str_replace("world", "PHP", $text);
CallWhat it does
str_replace("world", "PHP", "Hello world")Returns "Hello PHP".
str_replace(["a", "e"], ["4", "3"], $text)Replaces several values in one call.
str_replace("x", "y", $text, $count)Stores the number of replacements in $count.

For case-insensitive replacement, use str_ireplace(). For replacing by position, use substr_replace(). To replace patterns, use preg_replace().

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

Parameters

ParameterDescription
searchRequired. The value (or array of values) to find.
replaceRequired. The replacement text, or an array of replacements that matches search.
subjectRequired. The string or array of strings to search and replace in.
countOptional. A variable that receives the number of replacements made.

Return Value

Return ValueDescription
stringThe new string with all replacements applied (when subject is a string).
arrayAn array of new strings (when subject is an array).

PHP Examples

Example 1 — Replace One Word

The most common use: swap one piece of text for another.

PHP
<?php
$text = "Hello world";
$new = str_replace("world", "PHP", $text);

echo $new, PHP_EOL;

How It Works

  1. Store the original text.
  2. Pass the search value, the replacement, and the subject.
  3. PHP replaces every match of "world".
  4. The original $text stays unchanged; the new string is returned.

Example 2 — Case Matters

str_replace() is case-sensitive, so only exact matches change.

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

echo str_replace("hello", "Hi", $text), PHP_EOL;

How It Works

  1. The string contains "Hello" and "hello".
  2. The search value is lowercase "hello".
  3. Only the exact lowercase match is replaced.
  4. Use str_ireplace() if you want both to change.

Example 3 — Arrays and a Replacement Count

Replace several letters at once and count the changes.

PHP
<?php
$text = "leet area";
$new = str_replace(["a", "e"], ["4", "3"], $text, $count);

echo $new, PHP_EOL;
echo "Replacements: ", $count, PHP_EOL;

How It Works

  1. Pass two arrays: letters to find and what to put instead.
  2. Items are paired by position: a becomes 4, e becomes 3.
  3. There are two a letters and three e letters in the text.
  4. $count holds the total: 5.

Frequently Asked Questions

str_replace() replaces every occurrence of a search value in a string (or array of strings) with a replacement value and returns the result.
Yes. Use str_ireplace() for a case-insensitive version.
No. It returns a new string. Assign it back to a variable if you want to keep the change.
Pass an array of search values and an array of replacements, for example str_replace(['a', 'b'], ['1', '2'], $text).
Pass a variable as the fourth argument. PHP fills it with the total number of replacements made.

Next: str_rot13()

str_rot13() applies the ROT13 transformation, which shifts each letter 13 places in the al.

str_rot13() 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