Concept of the str_replace() Function

The str_replace() function is used to search for specific text within a string and replace it with another string.

PHP 
$text = 'I love apples.';
$replaced_text = str_replace('apples', 'oranges', $text);
echo $replaced_text;
Output

The str_replace() function searches a given string and replaces a specified substring with a replacement string.

Note:
If you want to search using a pattern instead of a fixed string, use preg_replace().

Syntax

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

// str_replace(search, replace, subject[, count]);

Parameters

Description of the str_replace() Function Parameters
$search Required. Specifies the string or array of strings to search for in the target string.
Case-sensitive.
$replace Required. Specifies the replacement string or array of strings to use in place of $search.
$subject Required. The input string or array to search and replace within.
The function searches this value for $search and replaces it with $replace.
$count Optional. A variable passed by reference that stores the number of replacements performed.
Defaults to null. This variable will be updated when str_replace() is called.

Note:
The str_replace() function is case-sensitive.
To perform a case-insensitive replacement, use the str_ireplace() function instead.

Return Values

The str_replace() function returns the string or array of strings after the replacements have been made.

Practical Examples

The following examples demonstrate how the str_replace() function behaves in various scenarios.

Replacing Specific Characters with Others

PHP 
$original_string = 'Hello, world! Hello, PHP!';
$new_string = str_replace('Hello', 'Hi', $original_string);

echo $new_string;  // Output: 'Hi, world! Hi, PHP!'

In this example, the str_replace() function replaces all occurrences of "Hello" with "Hi" in the original string. The resulting string is stored in the $new_string variable, which is then printed with echo.

Thus, the result of calling str_replace(), stored in $new_string, contains the modified string after replacement. This illustrates the function’s return value.

Removing a Specific Substring

PHP 
$str = 'This is a sample text.';
$new_str = str_replace('sample ', '', $str);
echo $new_str; // Output: 'This is a text.'

Here, $str contains the string "This is a sample text.". Using str_replace(), the word "sample " (including the trailing space) is replaced with an empty string, effectively removing it. The final string becomes "This is a text.".

This shows how str_replace() can be used to remove parts of a string.

Replacing Multiple Strings Using Arrays

PHP - With an Array of Strings 
$original_array = [
    'Apples are red.',
    'Bananas are yellow.',
    'Apples and bananas are tasty.'
];

$search = ['Apples', 'Bananas'];
$replace = ['Oranges', 'Grapes'];

$new_array = str_replace($search, $replace, $original_array);

print_r($new_array);

/* Output:
Array
(
    [0] => Oranges are red.
    [1] => Grapes are yellow.
    [2] => Oranges and grapes are tasty.
)
*/
PHP - With a Single String Containing Multiple Targets 
$original_string = 'Apples are red. Bananas are yellow. Apples and bananas are tasty.';

$search = ['Apples', 'Bananas'];
$replace = ['Oranges', 'Grapes'];

$new_string = str_replace($search, $replace, $original_string);

echo $new_string;
// Output: 'Oranges are red. Grapes are yellow. Oranges and grapes are tasty.'

In both examples above, the str_replace() function replaces multiple target strings by passing arrays for both search and replace parameters. This feature allows you to perform multiple replacements efficiently.

Using the $count Parameter to Track Replacements

The $count parameter is optional. It stores the number of replacements performed by str_replace() and is passed by reference. This parameter is useful when you want to count how many times a certain substring was replaced.

For example, suppose you want to count how many times a word appears in a string by replacing it:

PHP 
$original_string = 'Hello world! Hello PHP! Hello everyone!';
$search = 'Hello';
$replace = 'Hi';
$count = 0;

$new_string = str_replace($search, $replace, $original_string, $count);

echo $new_string;  // Output: 'Hi world! Hi PHP! Hi everyone!'
echo "The word '{$search}' was found {$count} times.";
// Output: The word 'Hello' was found 3 times.

In this example, the word "Hello" is searched for and replaced with "Hi". Because the $count variable is passed by reference, it stores the number of replacements performed, which in this case is 3.

The str_replace() function is very versatile and useful for many string manipulation tasks. Understanding how to use it effectively will greatly help you in various programming situations.

References

See also