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|array
Code 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 there
Code language: PHP (php)

Output:

Hi there Hello there
Code 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 hey
Code language: PHP (php)

Output:

hey hey hey
Code 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; // 2
Code 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 cat
Code 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; // 3
Code 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, bye
Code 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.
Did you find this tutorial useful?