<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Replace all occurrences of the search string with the replacement string</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.str-repeat.html">str_repeat</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.str-rot13.html">str_rot13</a></div>
<div class="up"><a href="ref.strings.html">String Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.str-replace" class="refentry">
<div class="refnamediv">
<h1 class="refname">str_replace</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">str_replace</span> — <span class="dc-title">Replace all occurrences of the search string with the replacement string</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.str-replace-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <span class="methodname"><strong>str_replace</strong></span>
( <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$search</code></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$replace</code></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$subject</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter reference">&$count</code></span>
] )</div>
<p class="para rdfs-comment">
This function returns a string or an array with all occurrences of
<em><code class="parameter">search</code></em> in <em><code class="parameter">subject</code></em>
replaced with the given <em><code class="parameter">replace</code></em> value.
</p>
<p class="para">
If you don't need fancy replacing rules (like regular expressions), you
should always use this function instead of <span class="function"><a href="function.preg-replace.html" class="function">preg_replace()</a></span>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.str-replace-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
If <em><code class="parameter">search</code></em> and <em><code class="parameter">replace</code></em> are
arrays, then <span class="function"><strong>str_replace()</strong></span> takes a value from each array
and uses them to search and replace on <em><code class="parameter">subject</code></em>. If
<em><code class="parameter">replace</code></em> has fewer values than
<em><code class="parameter">search</code></em>, then an empty string is used for the rest of
replacement values. If <em><code class="parameter">search</code></em> is an array and
<em><code class="parameter">replace</code></em> is a string, then this replacement string is
used for every value of <em><code class="parameter">search</code></em>. The converse would
not make sense, though.
</p>
<p class="para">
If <em><code class="parameter">search</code></em> or <em><code class="parameter">replace</code></em>
are arrays, their elements are processed first to last.
</p>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">search</code></em></span>
<dd>
<p class="para">
The value being searched for, otherwise known as the <em class="emphasis">needle</em>.
An array may be used to designate multiple needles.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">replace</code></em></span>
<dd>
<p class="para">
The replacement value that replaces found <em><code class="parameter">search</code></em>
values. An array may be used to designate multiple replacements.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">subject</code></em></span>
<dd>
<p class="para">
The string or array being searched and replaced on,
otherwise known as the <em class="emphasis">haystack</em>.
</p>
<p class="para">
If <em><code class="parameter">subject</code></em> is an array, then the search and
replace is performed with every entry of
<em><code class="parameter">subject</code></em>, and the return value is an array as
well.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">count</code></em></span>
<dd>
<p class="para">
If passed, this will be set to the number of replacements performed.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.str-replace-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
This function returns a string or an array with the replaced values.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.str-replace-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>5.0.0</td>
<td>
The <em><code class="parameter">count</code></em> parameter was added.
</td>
</tr>
<tr>
<td>4.3.3</td>
<td>
The behaviour of this function changed. In older versions a bug
existed when using arrays as both <em><code class="parameter">search</code></em> and
<em><code class="parameter">replace</code></em> parameters which caused empty
<em><code class="parameter">search</code></em> indexes to be skipped without advancing
the internal pointer on the <em><code class="parameter">replace</code></em> array.
This has been corrected in PHP 4.3.3, any scripts which relied on
this bug should remove empty search values prior to calling this
function in order to mimic the original behavior.
</td>
</tr>
<tr>
<td>4.0.5</td>
<td>
Most parameters can now be an <span class="type"><a href="language.types.array.html" class="type array">array</a></span>.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.str-replace-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4878">
<p><strong>Example #1 Basic <span class="function"><strong>str_replace()</strong></span> examples</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// Provides: <body text='black'><br /></span><span style="color: #0000BB">$bodytag </span><span style="color: #007700">= </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">"%body%"</span><span style="color: #007700">, </span><span style="color: #DD0000">"black"</span><span style="color: #007700">, </span><span style="color: #DD0000">"<body text='%body%'>"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Provides: Hll Wrld f PHP<br /></span><span style="color: #0000BB">$vowels </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"a"</span><span style="color: #007700">, </span><span style="color: #DD0000">"e"</span><span style="color: #007700">, </span><span style="color: #DD0000">"i"</span><span style="color: #007700">, </span><span style="color: #DD0000">"o"</span><span style="color: #007700">, </span><span style="color: #DD0000">"u"</span><span style="color: #007700">, </span><span style="color: #DD0000">"A"</span><span style="color: #007700">, </span><span style="color: #DD0000">"E"</span><span style="color: #007700">, </span><span style="color: #DD0000">"I"</span><span style="color: #007700">, </span><span style="color: #DD0000">"O"</span><span style="color: #007700">, </span><span style="color: #DD0000">"U"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$onlyconsonants </span><span style="color: #007700">= </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$vowels</span><span style="color: #007700">, </span><span style="color: #DD0000">""</span><span style="color: #007700">, </span><span style="color: #DD0000">"Hello World of PHP"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Provides: You should eat pizza, beer, and ice cream every day<br /></span><span style="color: #0000BB">$phrase </span><span style="color: #007700">= </span><span style="color: #DD0000">"You should eat fruits, vegetables, and fiber every day."</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$healthy </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"fruits"</span><span style="color: #007700">, </span><span style="color: #DD0000">"vegetables"</span><span style="color: #007700">, </span><span style="color: #DD0000">"fiber"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$yummy </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"pizza"</span><span style="color: #007700">, </span><span style="color: #DD0000">"beer"</span><span style="color: #007700">, </span><span style="color: #DD0000">"ice cream"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$newphrase </span><span style="color: #007700">= </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$healthy</span><span style="color: #007700">, </span><span style="color: #0000BB">$yummy</span><span style="color: #007700">, </span><span style="color: #0000BB">$phrase</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Provides: 2<br /></span><span style="color: #0000BB">$str </span><span style="color: #007700">= </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">"ll"</span><span style="color: #007700">, </span><span style="color: #DD0000">""</span><span style="color: #007700">, </span><span style="color: #DD0000">"good golly miss molly!"</span><span style="color: #007700">, </span><span style="color: #0000BB">$count</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$count</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4879">
<p><strong>Example #2 Examples of potential <span class="function"><strong>str_replace()</strong></span> gotchas</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// Order of replacement<br /></span><span style="color: #0000BB">$str </span><span style="color: #007700">= </span><span style="color: #DD0000">"Line 1\nLine 2\rLine 3\r\nLine 4\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$order </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"\r\n"</span><span style="color: #007700">, </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">, </span><span style="color: #DD0000">"\r"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$replace </span><span style="color: #007700">= </span><span style="color: #DD0000">'<br />'</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// Processes \r\n's first so they aren't converted twice.<br /></span><span style="color: #0000BB">$newstr </span><span style="color: #007700">= </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$order</span><span style="color: #007700">, </span><span style="color: #0000BB">$replace</span><span style="color: #007700">, </span><span style="color: #0000BB">$str</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Outputs F because A is replaced with B, then B is replaced with C, and so on...<br />// Finally E is replaced with F, because of left to right replacements.<br /></span><span style="color: #0000BB">$search </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'A'</span><span style="color: #007700">, </span><span style="color: #DD0000">'B'</span><span style="color: #007700">, </span><span style="color: #DD0000">'C'</span><span style="color: #007700">, </span><span style="color: #DD0000">'D'</span><span style="color: #007700">, </span><span style="color: #DD0000">'E'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$replace </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'B'</span><span style="color: #007700">, </span><span style="color: #DD0000">'C'</span><span style="color: #007700">, </span><span style="color: #DD0000">'D'</span><span style="color: #007700">, </span><span style="color: #DD0000">'E'</span><span style="color: #007700">, </span><span style="color: #DD0000">'F'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$subject </span><span style="color: #007700">= </span><span style="color: #DD0000">'A'</span><span style="color: #007700">;<br />echo </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$search</span><span style="color: #007700">, </span><span style="color: #0000BB">$replace</span><span style="color: #007700">, </span><span style="color: #0000BB">$subject</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Outputs: apearpearle pear<br />// For the same reason mentioned above<br /></span><span style="color: #0000BB">$letters </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'a'</span><span style="color: #007700">, </span><span style="color: #DD0000">'p'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$fruit </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'apple'</span><span style="color: #007700">, </span><span style="color: #DD0000">'pear'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$text </span><span style="color: #007700">= </span><span style="color: #DD0000">'a p'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$output </span><span style="color: #007700">= </span><span style="color: #0000BB">str_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$letters</span><span style="color: #007700">, </span><span style="color: #0000BB">$fruit</span><span style="color: #007700">, </span><span style="color: #0000BB">$text</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$output</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.str-replace-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>: <span class="simpara">This function is
binary-safe.</span></p></blockquote>
<div class="caution"><strong class="caution">Caution</strong>
<h1 class="title">Replacement order gotcha</h1>
<p class="para">
Because <span class="function"><strong>str_replace()</strong></span> replaces left to right, it might
replace a previously inserted value when doing multiple replacements.
See also the examples in this document.
</p>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
This function is case-sensitive. Use <span class="function"><a href="function.str-ireplace.html" class="function">str_ireplace()</a></span>
for case-insensitive replace.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.str-replace-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.str-ireplace.html" class="function" rel="rdfs-seeAlso">str_ireplace()</a> - Case-insensitive version of str_replace.</span></li>
<li class="member"> <span class="function"><a href="function.substr-replace.html" class="function" rel="rdfs-seeAlso">substr_replace()</a> - Replace text within a portion of a string</span></li>
<li class="member"> <span class="function"><a href="function.preg-replace.html" class="function" rel="rdfs-seeAlso">preg_replace()</a> - Perform a regular expression search and replace</span></li>
<li class="member"> <span class="function"><a href="function.strtr.html" class="function" rel="rdfs-seeAlso">strtr()</a> - Translate characters or replace substrings</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.str-repeat.html">str_repeat</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.str-rot13.html">str_rot13</a></div>
<div class="up"><a href="ref.strings.html">String Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
