PHP str_replace

Summary: in this tutorial, you’ll learn how to use the PHP str_replace() function to replace all occurrences of a substring with a new string

Introduction to the PHP str_replace() function

The PHP str_replace() function returns a new string with all occurrences of a substring replaced with another string.

The following shows the syntax of the str_replace() function:

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

The str_replace() has the following parameters:

• The $search is a substring to be replaced.
• The $replace is the replacement string that replaces the$search value.
• The $subject is the input string
• The $count returns the number of replacements that the function performed. The $count is optional.

If the $search and $replace arguments are arrays, the str_replace() takes each value from the $search array (from left to right) and replaces it with each value from the $replace array.

If the $replace array has fewer elements than the $search array, the str_replace() function uses an empty string for the replacement values.

If the $search is an array and the $replace is a string, then the str_replace() function replaces every element in the $search with the $replace string.

Note that the str_replace() doesn’t change the input string ($subject). It returns a new array with the $search replaced with the $replace.

PHP str_replace() function examples

Let’s take some examples of using the PHP str_replace() function.

Simple PHP str_replace() function examples

The following example uses the str_replace() function to replace the string 'Hello' with 'Hi' in the string 'Hello there':

<?php

$str = 'Hello there';
$new_str = str_replace('Hello', 'Hi', $str);

echo $new_str . '<br>'; // Hi there

echo $str . '<br>'; // Hello thereCode language: PHP (php)

Output:

Hi there
Hello thereCode language: PHP (php)

As shown in the output, the str_replace() doesn’t change the input string but returns a new string with the substring 'Hello' replaced by the string 'Hi';

The following example uses the str_replace() function to replace the substring 'bye' with the string 'hey' in the string 'bye bye bye':

<?php

$str = 'bye bye bye';
$new_str = str_replace('bye', 'hey', $str);

echo $new_str; // hey hey heyCode language: PHP (php)

Output:

hey hey heyCode language: PHP (php)

PHP str_replace() function with the count argument example

The following example uses the str_replace() function with the count argument:

<?php 

$str = 'Hi, hi, hi';
$new_str = str_replace('hi', 'bye', $str, $count);

echo $count; // 2Code language: PHP (php)

In this example, the str_replace() function replaces the substring 'hi' with the string 'bye' in the string 'Hi, hi, hi'.

The count returns two because the str_replace() function only replaces the substring 'hi' not 'Hi'.

PHP str_replace() function with multiple replacements example

The following example uses the str_replace() function to replace the fox with wolf and dog with cat in the string 'The quick brown fox jumps over the lazy dog':

<?php

$str = 'The quick brown fox jumps over the lazy dog';
$animals = ['fox', 'dog'];
$new_animals = ['wolf', 'cat'];

$new_str = str_replace($animals, $new_animals, $str);

echo $new_str;Code language: PHP (php)

Output:

The quick brown wolf jumps over the lazy catCode language: PHP (php)

Since the str_replace() function replaces left to right, it might replace previously replaced value while doing multiple replacements. For example:

<?php

$str = 'apple';

$fruits = ['apple', 'orange', 'banana'];
$replacements = ['orange', 'banana', 'strawberry'];

$new_str = str_replace($fruits, $replacements, $str, $count);

echo $new_str; // strawberry
echo $count; // 3Code language: PHP (php)

In this example, the string apple is replaced with orange, orange is replaced with banana, and banana is replaced with strawberry. The returned string is strawberry.

PHP str_ireplace() function

To search for a string case-insensitively and replace it with a replacement string, you use the str_ireplace() function. For example:

<?php

$str = 'Hi, hi, hi';
$new_str = str_ireplace('hi', 'bye', $str, $count);

echo $new_str; // bye, bye, byeCode language: PHP (php)

In this example, the str_ireplace() function replaces the substring 'hi' or 'Hi' with the string 'bye'.

Summary

• Use the str_replace() function to replace a substring with another string.
• Use the str_ireplace() function to search a substring case-insensitively and replace it with another string.