<!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>Perform a regular expression search and replace</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.preg-replace-callback.html">preg_replace_callback</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.preg-split.html">preg_split</a></div>
<div class="up"><a href="ref.pcre.html">PCRE Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.preg-replace" class="refentry">
<div class="refnamediv">
<h1 class="refname">preg_replace</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">preg_replace</span> — <span class="dc-title">Perform a regular expression search and replace</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.preg-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>preg_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">$pattern</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">$replacement</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">$limit</code><span class="initializer"> = -1</span></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter reference">&$count</code></span>
]] )</div>
<p class="para rdfs-comment">
Searches <em><code class="parameter">subject</code></em> for matches to
<em><code class="parameter">pattern</code></em> and replaces them with
<em><code class="parameter">replacement</code></em>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.preg-replace-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">pattern</code></em></span>
<dd>
<p class="para">
The pattern to search for. It can be either a string or an array with
strings.
</p>
<p class="para">
Several <a href="reference.pcre.pattern.modifiers.html" class="link">PCRE modifiers</a>
are also available, including the deprecated '<em>e</em>'
(PREG_REPLACE_EVAL), which is specific to this function.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">replacement</code></em></span>
<dd>
<p class="para">
The string or an array with strings to replace. If this parameter is a
string and the <em><code class="parameter">pattern</code></em> parameter is an array,
all patterns will be replaced by that string. If both
<em><code class="parameter">pattern</code></em> and <em><code class="parameter">replacement</code></em>
parameters are arrays, each <em><code class="parameter">pattern</code></em> will be
replaced by the <em><code class="parameter">replacement</code></em> counterpart. If
there are fewer elements in the <em><code class="parameter">replacement</code></em>
array than in the <em><code class="parameter">pattern</code></em> array, any extra
<em><code class="parameter">pattern</code></em>s will be replaced by an empty string.
</p>
<p class="para">
<em><code class="parameter">replacement</code></em> may contain references of the form
<em>\\<span class="replaceable">n</span></em> or (since PHP 4.0.4)
<em>$<span class="replaceable">n</span></em>, with the latter form
being the preferred one. Every such reference will be replaced by the text
captured by the <span class="replaceable">n</span>'th parenthesized pattern.
<span class="replaceable">n</span> can be from 0 to 99, and
<em>\\0</em> or <em>$0</em> refers to the text matched
by the whole pattern. Opening parentheses are counted from left to right
(starting from 1) to obtain the number of the capturing subpattern.
To use backslash in replacement, it must be doubled
(<em>"\\\\"</em> PHP string).
</p>
<p class="para">
When working with a replacement pattern where a backreference is
immediately followed by another number (i.e.: placing a literal number
immediately after a matched pattern), you cannot use the familiar
<em>\\1</em> notation for your backreference.
<em>\\11</em>, for example, would confuse
<span class="function"><strong>preg_replace()</strong></span> since it does not know whether you
want the <em>\\1</em> backreference followed by a literal
<em>1</em>, or the <em>\\11</em> backreference
followed by nothing. In this case the solution is to use
<em>\${1}1</em>. This creates an isolated
<em>$1</em> backreference, leaving the <em>1</em>
as a literal.
</p>
<p class="para">
When using the deprecated <em>e</em> modifier, this function escapes
some characters (namely <em>'</em>, <em>"</em>,
<em>\</em> and NULL) in the strings that replace the
backreferences. This is done to ensure that no syntax errors arise
from backreference usage with either single or double quotes (e.g.
<em>'strlen(\'$1\')+strlen("$2")'</em>). Make sure you are
aware of PHP's <a href="language.types.string.html" class="link">string
syntax</a> to know exactly how the interpreted string will look.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">subject</code></em></span>
<dd>
<p class="para">
The string or an array with strings to search and replace.
</p>
<p class="para">
If <em><code class="parameter">subject</code></em> is an array, then the search and
replace is performed on 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">limit</code></em></span>
<dd>
<p class="para">
The maximum possible replacements for each pattern in each
<em><code class="parameter">subject</code></em> string. Defaults to
<em>-1</em> (no limit).
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">count</code></em></span>
<dd>
<p class="para">
If specified, this variable will be filled with the number of
replacements done.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.preg-replace-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
<span class="function"><strong>preg_replace()</strong></span> returns an array if the
<em><code class="parameter">subject</code></em> parameter is an array, or a string
otherwise.
</p>
<p class="para">
If matches are found, the new <em><code class="parameter">subject</code></em> will
be returned, otherwise <em><code class="parameter">subject</code></em> will be
returned unchanged or <strong><code>NULL</code></strong> if an error occurred.
</p>
</div>
<div class="refsect1 errors" id="refsect1-function.preg-replace-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
An <strong><code>E_DEPRECATED</code></strong> level error is emitted when
passing in the "\e" modifier.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.preg-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.5.0</td>
<td>
The <em>/e</em> modifier is deprecated. Use
<span class="function"><a href="function.preg-replace-callback.html" class="function">preg_replace_callback()</a></span> instead. See the
<a href="reference.pcre.pattern.modifiers.html#reference.pcre.pattern.modifiers.eval" class="link">PREG_REPLACE_EVAL</a>
documentation for additional information about security risks.
</td>
</tr>
<tr>
<td>5.1.0</td>
<td>
Added the <em><code class="parameter">count</code></em> parameter
</td>
</tr>
<tr>
<td>4.0.4</td>
<td>
Added the '$n' form for the <em><code class="parameter">replacement</code></em> parameter
</td>
</tr>
<tr>
<td>4.0.2</td>
<td>
Added the <em><code class="parameter">limit</code></em> parameter
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.preg-replace-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4797">
<p><strong>Example #1 Using backreferences followed by numeric literals</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$string </span><span style="color: #007700">= </span><span style="color: #DD0000">'April 15, 2003'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$pattern </span><span style="color: #007700">= </span><span style="color: #DD0000">'/(\w+) (\d+), (\d+)/i'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$replacement </span><span style="color: #007700">= </span><span style="color: #DD0000">'${1}1,$3'</span><span style="color: #007700">;<br />echo </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$pattern</span><span style="color: #007700">, </span><span style="color: #0000BB">$replacement</span><span style="color: #007700">, </span><span style="color: #0000BB">$string</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
April1,2003
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4798">
<p><strong>Example #2 Using indexed arrays with <span class="function"><strong>preg_replace()</strong></span></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$string </span><span style="color: #007700">= </span><span style="color: #DD0000">'The quick brown fox jumped over the lazy dog.'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$patterns </span><span style="color: #007700">= array();<br /></span><span style="color: #0000BB">$patterns</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">] = </span><span style="color: #DD0000">'/quick/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$patterns</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">] = </span><span style="color: #DD0000">'/brown/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$patterns</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">] = </span><span style="color: #DD0000">'/fox/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$replacements </span><span style="color: #007700">= array();<br /></span><span style="color: #0000BB">$replacements</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">] = </span><span style="color: #DD0000">'bear'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$replacements</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">] = </span><span style="color: #DD0000">'black'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$replacements</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">] = </span><span style="color: #DD0000">'slow'</span><span style="color: #007700">;<br />echo </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$patterns</span><span style="color: #007700">, </span><span style="color: #0000BB">$replacements</span><span style="color: #007700">, </span><span style="color: #0000BB">$string</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
The bear black slow jumped over the lazy dog.
</pre></div>
</div>
<div class="example-contents"><p>
By ksorting patterns and replacements, we should get what we wanted.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />ksort</span><span style="color: #007700">(</span><span style="color: #0000BB">$patterns</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">ksort</span><span style="color: #007700">(</span><span style="color: #0000BB">$replacements</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$patterns</span><span style="color: #007700">, </span><span style="color: #0000BB">$replacements</span><span style="color: #007700">, </span><span style="color: #0000BB">$string</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
The slow black bear jumped over the lazy dog.
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4799">
<p><strong>Example #3 Replacing several values</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$patterns </span><span style="color: #007700">= array (</span><span style="color: #DD0000">'/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'/^\s*{(\w+)}\s*=/'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$replace </span><span style="color: #007700">= array (</span><span style="color: #DD0000">'\3/\4/\1\2'</span><span style="color: #007700">, </span><span style="color: #DD0000">'$\1 ='</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(</span><span style="color: #0000BB">$patterns</span><span style="color: #007700">, </span><span style="color: #0000BB">$replace</span><span style="color: #007700">, </span><span style="color: #DD0000">'{startDate} = 1999-5-27'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
$startDate = 5/27/1999
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4800">
<p><strong>Example #4 Strip whitespace</strong></p>
<div class="example-contents"><p>
This example strips excess whitespace from a string.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$str </span><span style="color: #007700">= </span><span style="color: #DD0000">'foo o'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$str </span><span style="color: #007700">= </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(</span><span style="color: #DD0000">'/\s\s+/'</span><span style="color: #007700">, </span><span style="color: #DD0000">' '</span><span style="color: #007700">, </span><span style="color: #0000BB">$str</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// This will be 'foo o' now<br /></span><span style="color: #007700">echo </span><span style="color: #0000BB">$str</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-4801">
<p><strong>Example #5 Using the <em><code class="parameter">count</code></em> parameter</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$count </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /><br />echo </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'/\d/'</span><span style="color: #007700">, </span><span style="color: #DD0000">'/\s/'</span><span style="color: #007700">), </span><span style="color: #DD0000">'*'</span><span style="color: #007700">, </span><span style="color: #DD0000">'xp 4 to'</span><span style="color: #007700">, -</span><span style="color: #0000BB">1 </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">; </span><span style="color: #FF8000">//3<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
xp***to
3
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.preg-replace-notes">
<h3 class="title">Notes</h3>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
When using arrays with <em><code class="parameter">pattern</code></em> and
<em><code class="parameter">replacement</code></em>, the keys are processed in the order
they appear in the array. This is <em class="emphasis">not necessarily</em> the
same as the numerical index order. If you use indexes to identify which
<em><code class="parameter">pattern</code></em> should be replaced by which
<em><code class="parameter">replacement</code></em>, you should perform a
<span class="function"><a href="function.ksort.html" class="function">ksort()</a></span> on each array prior to calling
<span class="function"><strong>preg_replace()</strong></span>.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.preg-replace-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><a href="pcre.pattern.html" class="link">PCRE Patterns</a></li>
<li class="member"> <span class="function"><a href="function.preg-filter.html" class="function" rel="rdfs-seeAlso">preg_filter()</a> - Perform a regular expression search and replace</span></li>
<li class="member"> <span class="function"><a href="function.preg-match.html" class="function" rel="rdfs-seeAlso">preg_match()</a> - Perform a regular expression match</span></li>
<li class="member"> <span class="function"><a href="function.preg-replace-callback.html" class="function" rel="rdfs-seeAlso">preg_replace_callback()</a> - Perform a regular expression search and replace using a callback</span></li>
<li class="member"> <span class="function"><a href="function.preg-split.html" class="function" rel="rdfs-seeAlso">preg_split()</a> - Split string by a regular expression</span></li>
<li class="member"> <span class="function"><a href="function.preg-last-error.html" class="function" rel="rdfs-seeAlso">preg_last_error()</a> - Returns the error code of the last PCRE regex execution</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.preg-replace-callback.html">preg_replace_callback</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.preg-split.html">preg_split</a></div>
<div class="up"><a href="ref.pcre.html">PCRE Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
