PHP str_replace(): Replace Text in a String

str_replace($search, $replace, $subject) returns a copy of $subject with every occurrence of $search replaced by $replace. str_replace('world', 'PHP', 'Hello world') returns "Hello PHP".

<?php
$text = 'I like cats. cats are great.';

$new = str_replace('cats', 'dogs', $text);

echo $new, "\n";
echo $text, "\n";   // the original is unchanged

The function returns the new string; it does not modify the variable you pass in. Assign the result, even back to the same variable: $text = str_replace(...).

Syntax

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

Each of the first three arguments can be a string or an array. If $subject is an array, the replacement runs on every element and you get an array back with the same keys: str_replace('.txt', '.md', ['a.txt', 'b.txt']) returns ['a.md', 'b.md']. The search is case-sensitive and matches plain text, not patterns. For patterns use preg_replace().

Replace several strings at once

Pass arrays for $search and $replace. The first search value is replaced by the first replacement, the second by the second, and so on. If $replace is a single string, every search value is replaced by it, which is the short way to remove a set of characters.

<?php
$template = 'Hello {name}, your order {id} has shipped.';

echo str_replace(['{name}', '{id}'], ['Ada', '#1042'], $template), "\n";

// One replacement for every search value: remove punctuation
echo str_replace(['.', ',', '!', '?'], '', 'Hi, there! Ready? Yes.'), "\n";

// Fewer replacements than searches: the missing ones are ""
echo str_replace(['a', 'b', 'c'], ['1'], 'abcabc'), "\n";

The order trap and strtr()

With arrays, str_replace() runs one replacement after another over the whole string. A later search can match text that an earlier replacement just inserted. strtr() with an array replaces everything in a single pass, tries the longest keys first, and never touches text it has already replaced.

<?php
$s = 'apple banana';

// apple -> banana, then every banana (including the new one) -> cherry
echo str_replace(['apple', 'banana'], ['banana', 'cherry'], $s), "\n";

// One pass: each original word is replaced once
echo strtr($s, ['apple' => 'banana', 'banana' => 'cherry']), "\n";

Use strtr() for swaps and for template placeholders that might appear in the values.

Count the replacements

The fourth argument is filled with the number of replacements made. Pass a variable; PHP writes into it.

<?php
$text = 'one fish, two fish, red fish, blue fish';

$result = str_replace('fish', 'cat', $text, $count);

echo $result, "\n";
echo "Replaced $count times\n";

Case-insensitive replace with str_ireplace

str_ireplace() takes the same arguments and ignores case when matching. The replacement is inserted exactly as you wrote it.

<?php
$text = 'PHP, php and Php';

echo str_replace('php', 'Python', $text), "\n";
echo str_ireplace('php', 'Python', $text), "\n";

str_ireplace() only folds ASCII letters. For case-insensitive replacement of accented or Cyrillic letters, use preg_replace() with the i and u modifiers.

Replace only the first occurrence

str_replace() always replaces everything. To replace just the first match, find it with strpos() and cut it out with substr_replace():

<?php
function replaceFirst(string $search, string $replace, string $subject): string
{
    $pos = strpos($subject, $search);
    if ($pos === false) {
        return $subject;
    }
    return substr_replace($subject, $replace, $pos, strlen($search));
}

echo replaceFirst('a', 'A', 'banana'), "\n";

// The same with a regex and a limit of 1
echo preg_replace('/' . preg_quote('a', '/') . '/', 'A', 'banana', 1), "\n";

For the last occurrence, use strrpos() in place of strpos().

Remove spaces, newlines and other characters

Replacing with an empty string removes the text. A common clean-up removes line breaks or all spaces, and Japanese input often contains full-width spaces (　, U+3000) that a normal " " search does not match.

<?php
$text = "line one\r\nline two\nline three";
echo str_replace(["\r\n", "\n", "\r"], ' ', $text), "\n";

$phone = '090 1234 5678';
echo str_replace(' ', '', $phone), "\n";

$name = '山田　太郎';
echo str_replace('　', ' ', $name), "\n";   // full-width space to normal space

Put "\r\n" before "\n" and "\r" in the array, so a Windows line break becomes one space and not two.