The PHP str_replace() function replaces words or sections (known as substrings) in a string with other words or sentences, allowing you to modify or reformat text values (find and replace text).
str_replace ( $search , $replace , $subject [, &$count ] )
- $search is the string value being searched for – it can even be an array of strings if you wish to search for multiple values
- $replace is the value you wish to replace the $search value with – it can also be an array if you wish to replace multiple values
- If using arrays for $search and $replace, the values in $search will be replaced with the value at the same position in $replace
- $subject is the string you wish to perform the find/replace on
- $subject can also be an array of strings, and the find/replace will be performed on each string in the array
- $count can be used to limit the number of replacements performed and is optional
- If it is not present no limit will be used and all found occurrences of $search in $subject will be replaced
- Be aware of the use of & prefixing the $count variable! This means the variable is passed as a reference – you must pass a variable here, you can’t just pass a number value directly
Replacing a Single String
Let’s make some replace values singularly, and using arrays, on a string describing a bunch of animals:
$animals = "There was a pink cat, red dog, blue bird and a pink horse."; $replaced = str_replace("pink", "green", $animals); echo $replaced; // "There was a green cat, red dog, blue bird and a green horse."
Replacing Multiple Strings Using Arrays
It’s also possible to replace multiple values at once. Replacement values will be matched to search values by their position in their respective arrays:
$animals = "There was a pink cat, red dog, blue bird and a pink horse."; $search = ["pink", "red"]; $replace = ["green", "orange"]; $replaced = str_replace($search, $replace, $animals); echo $replaced; // "There was a green cat, orange dog, blue bird and a green horse."
Limiting the Number of Replacements
$animals = "There was a pink cat, red dog, blue bird and a pink horse."; $count = 1; $replaced = str_replace("pink", "green", $animals, $count); echo $replaced; // "There was a green cat, red dog, blue bird and a pink horse."
- Only the first instance of “pink” was replaced with “green” as we told str_replace() to limit the number of replacements to 1 using $count
str_replace() is one of the key tools used to manipulate data in PHP. Its ability to search and replace using arrays of values for both the searched-for values and replacement values, and defining limits to replacements, can all be used in different combinations for the intended result.
To view the official documentation for the PHP str_replace() function: