Replace Strings in PHP

On this page we describe and demonstrate the following PHP functions for replacing strings: str_replace, substr_replace, and strtr.

str_replace

Pass the string to search for, the string to replace it with, and the string to act on. All instances of the search string will be replaced with the replacement string in the string returned by the str_replace function. That describes the basic usage of str_replace. The following demonstrates:

$str = 'John Doe';
// search for 'John', replace with 'Jane' in $str
echo str_replace('John', 'Jane', $str); // Jane Doe

However, the str_replace function provides a lot more flexibility than that simple usage demonstrates. Each of the arguments can be strings, or they can be arrays containing string elements.

To facilitate our discussion we will name the arguments just as they are in the PHP Manual. The first argument, search, is what you are looking for. The second argument, replace, is what you will replace search with. The third argument, subject, is the string or array you are searching in.

Next we demonstrate using the str_replace function for search and replace in an array subject while passing strings for the search and replace arguments:

$ar = ['img_01.jpg', 'img_02.jpg', 'img_03.jpg'];
// replace underscores with hyphens in $ar
print_r( str_replace('_', '-', $ar) );
/* View Source display:
Array
(
    [0] => img-01.jpg
    [1] => img-02.jpg
    [2] => img-03.jpg
)
*/

As the result above shows, the underscore (search argument) in each element of the subject array has been replaced with a hyphen (replace argument) in the array returned by str_replace. Note that if the subject argument passed to str_replace is an array, an array will be returned.

If the search argument is an array and the replace argument is a string, each element of the search array will be searched for in turn. Matching strings in subject will be replaced with the replace string. We demonstrate below with a string subject that lists file names with hyphens and underscores. The search argument is an array (['_','-']), and the replace argument is an empty string:

// subject string
$str = 'memo-1.txt, memo-2.txt, memo-3.txt, img_01.jpg, img_02.jpg, img_03.jpg';
// replace underscores and hyphens with an empty string
echo str_replace( ['_', '-'], '', $str);
// memo1.txt, memo2.txt, memo3.txt, img01.jpg, img02.jpg, img03.jpg

As we can see from the result, hyphens and underscores have been removed in the string returned by str_replace.

If subject is an array and search is an array, each element of subject will be searched in turn for each element of search. The following example is like the one above except the file names with hyphens and underscores are elements in an array rather than listed in a string:

// subject array
$ar = ['memo-1.txt', 'memo-2.txt', 'memo-3.txt', 'img_01.jpg', 'img_02.jpg', 'img_03.jpg'];
// replace underscores and hyphens with an empty string
print_r( str_replace( ['_', '-'], '', $ar) );
/* View Source display:
Array
(
    [0] => memo1.txt
    [1] => memo2.txt
    [2] => memo3.txt
    [3] => img01.jpg
    [4] => img02.jpg
    [5] => img03.jpg
)
*/

As you can see, the hyphens and underscores have been removed from each element in the array returned by str_replace.

If search and replace arguments are both arrays, subject will be searched for each element in the search array in turn and replaced with the corresponding element in the replace array.

Case Insensitive Search and Replace

The str_ireplace function is the case-insensitive equivalent of the str_replace function.

substr_replace

The substr_replace function differs from the str_replace function in that you are not providing a string to search for in the subject, but instead providing a location and optional length for the replacement.

In the following basic example, we provide a subject string, a replacement string, and a starting location as arguments to substr_replace, then display the string returned using echo:

$str = 'John Doe';
/* substr_replace arguments:
 * subject, replacement, start location, length (optional) */
// replace characters in $str with 'Q. Public', from 5 to end
echo substr_replace($str, 'Q. Public', 5); // John Q. Public

If length is not provided, it defaults to the end of the string, as the above example shows.

If length is 0, the replacement string is inserted at start and does not replace any existing characters in subject:

$str = '1234';
// insert '*' at location 2
echo substr_replace($str, '*', 2, 0); // 12*34

The length argument can be negative to indicate the number of characters at the end of the string to exclude. The following example demonstrates using substr_replace to replace all but the last four characters of a string with asterisks:

$val = 1111222233334444;
echo substr_replace($val, str_repeat('*', 12), 0, -4); // ************4444

We use the str_repeat function to insert 12 asterisks for us as the replace argument. Notice that the value passed as the subject argument is not enclosed in quotes. Even though it is a numeric, the substr_replace function is able to successfully perform the replacement. Find out about type conversion in PHP.

The subject can be a string or an array. If it is an array, the other arguments can also be arrays. The example below demonstrates with arrays for the subject and replacement arguments:

// array for subject argument
$subject = ['img_01.jpg', 'img_02.jpg', 'img_03.jpg'];
// array for replacement argument
$replace = ['one', 'two', 'three'];
// start location: 4, length: 2
print_r( substr_replace($subject, $replace, 4, 2) );
/* View Source display
Array
(
    [0] => img_one.jpg
    [1] => img_two.jpg
    [2] => img_three.jpg
)
*/

As you can see in the result shown above, elements in the $replace array are applied to the corresponding elements in the $subject array. Since the start and length arguments are not arrays, those values are applied to each element in the $subject array.

As with the str_replace function, if the subject argument is an array, the substr_replace function returns an array.

strtr

The strtr function can have two or three arguments. The first argument is a subject string. When invoked with three arguments, the second and third are search and replace strings used for character by character substitution. That is, each character in the search string is replaced by the corresponding character in the replace string:

$str = 'img_1.jpg, img_2.jpg, img_3.jpg';
/* strtr arguments:
 * subject string, search characters, replace characters */
echo strtr($str, '_123', '-abc');
// img-a.jpg, img-b.jpg, img-c.jpg 

In the string returned by the strtr function, underscores in the subject string are replaced by hyphens, 1 is replaced by a, 2 is replaced by b, and 3 is replaced by c.

When the strtr function is invoked with two arguments, the second argument is an associative array of search-replace pairs in which each key is a search string and its value is the corresponding replace string:

$str = 'img_01.jpg, img_02.jpg, img_03.jpg';
// array of search-replace pairs
$sub = ['01'=>'one', '02'=>'two', '03'=>'three'];
echo strtr($str, $sub);
// img_one.jpg, img_two.jpg, img_three.jpg 

As you can see, in the string returned by the strtr function invocation above, '01' is replaced by 'one', '02' by 'two', and '03' by 'three'.