How to Replace String in PHP

Replacing part of a PHP string is straightforward with str_replace(). It searches for literal text and returns the subject with matching text replaced. Use it for ordinary text transformations; it does not validate or sanitize untrusted input.

Use str_replace() to replace text in a PHP string

The function accepts the text to find, its replacement, and the string or array to search. The match is literal: for example, a dollar sign is just another character to search for. In a PHP double-quoted string, write "$" carefully because $ begins variable interpolation; a single-quoted string such as '$' expresses the literal dollar sign directly.

Run this example:

<?php
$subject = 'Hello World!';
echo str_replace('World', 'PHP', $subject) . PHP_EOL;

Hello PHP!

PHP_EOL ends the displayed line with the platform’s line separator.

To replace a dollar sign, pass '$' as the search value and a string such as 'USD ' as the replacement. The function itself does not require special escaping for $; the quoting rules of the PHP string literal determine its value.

Understand the arguments, return value, and replacement count

$search, $replace, and $subject are the required arguments. $search is the literal text to find, $replace is the text to put in its place, and $subject is the string or array of strings to process. The function returns the modified string when the subject is a string, or an array of modified strings when the subject is an array. If there is no match, the subject remains unchanged.

An optional fourth argument, $count, is passed by reference. PHP sets it to the total number of replacements made across the subject; initialize a variable before passing it when you need that count. The count is output from the call, not a limit on how many replacements are made.

For example, str_replace('cat', 'dog', 'cat and cat', $count) returns dog and dog and sets $count to 2. This is a syntax illustration and is not presented as executed output.

Replace several values with arrays

Pass arrays for $search and $replace to apply corresponding replacements in one call. Each search value is paired with its replacement at the same position. For example, the following expression changes both words in the sentence:

str_replace(['PHP', 'great'], ['Python', 'useful'], 'PHP is great')

It returns Python is useful. PHP applies array pairs in order, so a replacement can introduce text that a later search value then matches. If you want each decision to depend only on the original text, avoid overlapping pairs or use a parser designed for that input format.

Handle case-sensitive and case-insensitive matches

str_replace() matches letter case: searching for 'world' does not match 'World'. Use str_ireplace() when the search should ignore case. For example, str_ireplace('world', 'PHP', 'Hello World!') returns Hello PHP!. Choose the case-insensitive function only when that behavior is intended, since it can replace differently cased occurrences as well.