str_replace()

The PHP str_replace() function replaces all occurrences of a search string with a replacement string. It is useful for finding and substituting specific patterns within larger text. Below, we cover the syntax, key features, and usage examples.

The str_replace() function is used to replace all occurrences of a string within another string. The syntax of the str_replace() function is as follows:

The PHP syntax of the str_replace()

str_replace($search, $replace, $subject, $count = null)

The function takes three required parameters and one optional parameter: $search, $replace, $subject, and $count.

• $search: The string, or array of strings, to search for.
• $replace: The string, or array of strings, to replace with.
• $subject: The string, or array of strings, to search within.
• $count (optional): A variable passed by reference that is filled with the number of replacements made.

The function returns the modified $subject. The original string is never changed in place, so you must capture the return value. str_replace() is case-sensitive — "World" and "world" are treated as different strings. If you need to ignore case, use str_ireplace() instead.

A basic example

Here is the simplest way to use the str_replace() function — replacing one word with another:

Example of PHP str_replace()

In this example, the string variable $string contains the phrase "The quick brown fox jumps over the lazy dog." We replace the word "brown" with "red" by passing "brown" as $search and "red" as $replace. The output is:

The quick red fox jumps over the lazy dog.

Every occurrence is replaced — not just the first one. If the search string appeared three times, all three would be substituted in a single call.

Replacing multiple strings at once

When $search and $replace are arrays, each element of $search is replaced by the element at the same index in $replace. The optional fourth argument, $count, is passed by reference and receives the total number of replacements:

Example with arrays and $count

<?php
$search = ["brown", "fox"];
$replace = ["red", "bear"];
$subject = "The quick brown fox jumps over the lazy dog.";
$count = 0;
$result = str_replace($search, $replace, $subject, $count);
echo $result; // Output: The quick red bear jumps over the lazy dog.
echo "Replacements made: $count"; // Output: Replacements made: 2
?>

If $replace is a single string but $search is an array, that one string is used for all matches:

<?php
$result = str_replace(["a", "e", "i"], "*", "education");
echo $result; // Output: *duc*t*on
?>

A gotcha: replacements cascade

Array replacements are applied in order, and each one runs against the result of the previous one. This means a value you just inserted can be matched again by a later search term:

<?php
$count = 0;
$result = str_replace(["A", "B"], ["B", "C"], "A", $count);
echo $result;        // Output: C
echo "\n";
echo "Replacements: $count"; // Output: Replacements: 2
?>

Here "A" becomes "B" in the first pass, then that "B" becomes "C" in the second pass — so the final result is "C", with two replacements counted. Order your search/replace pairs carefully to avoid this, or use strtr() when you need every pair applied exactly once.

When to use str_replace()

• Use str_replace() for fast, literal find-and-replace where you know the exact text.
• Use str_ireplace() when the match should ignore case.
• Use substr_replace() to replace a portion of a string by position rather than by content.
• Use preg_replace() when you need pattern matching with regular expressions.

The str_replace() function provides a straightforward, efficient way to search and replace text in PHP. Because it works on plain strings without regex overhead, it is the right tool whenever you are matching exact, literal text.

Practice