<!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>Pattern Modifiers</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="regexp.reference.performance.html">Performance</a></div>
<div class="next" style="text-align: right; float: right;"><a href="reference.pcre.pattern.differences.html">Differences From Perl</a></div>
<div class="up"><a href="pcre.pattern.html">PCRE Patterns</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="reference.pcre.pattern.modifiers" class="article">
<h1>Pattern Modifiers</h1>
<p class="para">
The current possible PCRE modifiers are listed below. The names
in parentheses refer to internal PCRE names for these modifiers.
Spaces and newlines are ignored in modifiers, other characters cause error.
</p>
<p class="para">
<blockquote class="blockquote">
<dl>
<dt>
<span class="term"><em class="emphasis">i</em> (<em>PCRE_CASELESS</em>)</span>
<dd>
<span class="simpara">
If this modifier is set, letters in the pattern match both
upper and lower case letters.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">m</em> (<em>PCRE_MULTILINE</em>)</span>
<dd>
<span class="simpara">
By default, PCRE treats the subject string as consisting of a
single "line" of characters (even if it actually contains
several newlines). The "start of line" metacharacter (^)
matches only at the start of the string, while the "end of
line" metacharacter ($) matches only at the end of the
string, or before a terminating newline (unless
<em class="emphasis">D</em> modifier is set). This is the same as
Perl.
</span>
<span class="simpara">
When this modifier is set, the "start of line" and "end of
line" constructs match immediately following or immediately
before any newline in the subject string, respectively, as
well as at the very start and end. This is equivalent to
Perl's /m modifier. If there are no "\n" characters in a
subject string, or no occurrences of ^ or $ in a pattern,
setting this modifier has no effect.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">s</em> (<em>PCRE_DOTALL</em>)</span>
<dd>
<span class="simpara">
If this modifier is set, a dot metacharacter in the pattern
matches all characters, including newlines. Without it,
newlines are excluded. This modifier is equivalent to Perl's
/s modifier. A negative class such as [^a] always matches a
newline character, independent of the setting of this
modifier.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">x</em> (<em>PCRE_EXTENDED</em>)</span>
<dd>
<span class="simpara">
If this modifier is set, whitespace data characters in the
pattern are totally ignored except when escaped or inside a
character class, and characters between an unescaped #
outside a character class and the next newline character,
inclusive, are also ignored. This is equivalent to Perl's /x
modifier, and makes it possible to include commentary inside
complicated patterns. Note, however, that this applies only
to data characters. Whitespace characters may never appear
within special character sequences in a pattern, for example
within the sequence (?( which introduces a conditional
subpattern.
</span>
</dd>
</dt>
<dt id="reference.pcre.pattern.modifiers.eval">
<span class="term"><em class="emphasis">e</em> (<em>PREG_REPLACE_EVAL</em>)</span>
<dd>
<div class="warning"><strong class="warning">Warning</strong><p class="simpara">This feature has been
<em class="emphasis">DEPRECATED</em> as of PHP 5.5.0. Relying on this feature
is highly discouraged.</p></div>
<span class="simpara">
If this deprecated modifier is set, <span class="function"><a href="function.preg-replace.html" class="function">preg_replace()</a></span>
does normal substitution of backreferences in the
replacement string, evaluates it as PHP code, and uses the
result for replacing the search string.
Single quotes, double quotes, backslashes (<em>\</em>) and NULL chars will
be escaped by backslashes in substituted backreferences.
</span>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
The <span class="function"><a href="function.addslashes.html" class="function">addslashes()</a></span> function is run on each matched backreference before
the substitution takes place. As such, when the backreference
is used as a quoted string, escaped characters will be converted
to literals. However, characters which are escaped, which would
normally not be converted, will retain their slashes. This makes
use of this modifier very complicated.
</p>
</div>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
Make sure that <em><code class="parameter">replacement</code></em> constitutes a valid PHP code string,
otherwise PHP will complain about a parse error at the line containing
<span class="function"><a href="function.preg-replace.html" class="function">preg_replace()</a></span>.
</p>
</div>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
Use of this modifier is <em class="emphasis">discouraged</em>, as it can easily introduce
security vulnerabilites:
</p>
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$html </span><span style="color: #007700">= </span><span style="color: #0000BB">$_POST</span><span style="color: #007700">[</span><span style="color: #DD0000">'html'</span><span style="color: #007700">];<br /><br /></span><span style="color: #FF8000">// uppercase headings<br /></span><span style="color: #0000BB">$html </span><span style="color: #007700">= </span><span style="color: #0000BB">preg_replace</span><span style="color: #007700">(<br /> </span><span style="color: #DD0000">'(<h([1-6])>(.*?)</h\1>)e'</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'"<h$1>" . strtoupper("$2") . "</h$1>"'</span><span style="color: #007700">,<br /> </span><span style="color: #0000BB">$html<br /></span><span style="color: #007700">);</span>
</span>
</code></div>
</div>
</div>
<p class="para">
The above example code can be easily exploited by passing in a string such as
<em><h1>{${eval($_GET[php_code])}}</h1></em>. This gives
the attacker the ability to execute arbitrary PHP code and as such gives him
nearly complete access to your server.
</p>
<p class="para">
To prevent this kind of remote code execution vulnerability the
<span class="function"><a href="function.preg-replace-callback.html" class="function">preg_replace_callback()</a></span> function should be used instead:
</p>
<div class="informalexample">
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$html </span><span style="color: #007700">= </span><span style="color: #0000BB">$_POST</span><span style="color: #007700">[</span><span style="color: #DD0000">'html'</span><span style="color: #007700">];<br /><br /></span><span style="color: #FF8000">// uppercase headings<br /></span><span style="color: #0000BB">$html </span><span style="color: #007700">= </span><span style="color: #0000BB">preg_replace_callback</span><span style="color: #007700">(<br /> </span><span style="color: #DD0000">'(<h([1-6])>(.*?)</h\1>)'</span><span style="color: #007700">,<br /> function (</span><span style="color: #0000BB">$m</span><span style="color: #007700">) {<br /> return </span><span style="color: #DD0000">"<h</span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]</span><span style="color: #DD0000">>" </span><span style="color: #007700">. </span><span style="color: #0000BB">strtoupper</span><span style="color: #007700">(</span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">]) . </span><span style="color: #DD0000">"</h</span><span style="color: #0000BB">$m</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]</span><span style="color: #DD0000">>"</span><span style="color: #007700">;<br /> },<br /> </span><span style="color: #0000BB">$html<br /></span><span style="color: #007700">);</span>
</span>
</code></div>
</div>
</div>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Only <span class="function"><a href="function.preg-replace.html" class="function">preg_replace()</a></span> uses this modifier;
it is ignored by other PCRE functions.
</p>
</p></blockquote>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">A</em> (<em>PCRE_ANCHORED</em>)</span>
<dd>
<span class="simpara">
If this modifier is set, the pattern is forced to be
"anchored", that is, it is constrained to match only at the
start of the string which is being searched (the "subject
string"). This effect can also be achieved by appropriate
constructs in the pattern itself, which is the only way to
do it in Perl.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">D</em> (<em>PCRE_DOLLAR_ENDONLY</em>)</span>
<dd>
<span class="simpara">
If this modifier is set, a dollar metacharacter in the pattern
matches only at the end of the subject string. Without this
modifier, a dollar also matches immediately before the final
character if it is a newline (but not before any other
newlines). This modifier is ignored if <em class="emphasis">m</em>
modifier is set. There is no equivalent to this modifier in
Perl.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">S</em></span>
<dd>
<span class="simpara">
When a pattern is going to be used several times, it is
worth spending more time analyzing it in order to speed up
the time taken for matching. If this modifier is set, then
this extra analysis is performed. At present, studying a
pattern is useful only for non-anchored patterns that do not
have a single fixed starting character.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">U</em> (<em>PCRE_UNGREEDY</em>)</span>
<dd>
<span class="simpara">
This modifier inverts the "greediness" of the quantifiers so
that they are not greedy by default, but become greedy if
followed by <em>?</em>. It is not compatible with Perl. It can also
be set by a (<em>?U</em>)
<a href="regexp.reference.internal-options.html" class="link">modifier setting within
the pattern</a> or by a question mark behind a quantifier (e.g.
<em>.*?</em>).
</span>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
It is usually not possible to match more than <a href="pcre.configuration.html#ini.pcre.backtrack-limit" class="link">pcre.backtrack_limit</a>
characters in ungreedy mode.
</p>
</p></blockquote>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">X</em> (<em>PCRE_EXTRA</em>)</span>
<dd>
<span class="simpara">
This modifier turns on additional functionality of PCRE that
is incompatible with Perl. Any backslash in a pattern that
is followed by a letter that has no special meaning causes
an error, thus reserving these combinations for future
expansion. By default, as in Perl, a backslash followed by a
letter with no special meaning is treated as a literal.
There are at present no other features controlled by this
modifier.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">J</em> (<em>PCRE_INFO_JCHANGED</em>)</span>
<dd>
<span class="simpara">
The (?J) internal option setting changes the local <em>PCRE_DUPNAMES</em>
option. Allow duplicate names for subpatterns.
</span>
</dd>
</dt>
<dt>
<span class="term"><em class="emphasis">u</em> (<em>PCRE_UTF8</em>)</span>
<dd>
<span class="simpara">
This modifier turns on additional functionality of PCRE that
is incompatible with Perl. Pattern strings are treated as
UTF-8. This modifier is available from PHP 4.1.0 or greater
on Unix and from PHP 4.2.3 on win32.
UTF-8 validity of the pattern is checked since PHP 4.3.5.
</span>
</dd>
</dt>
</dl>
</blockquote>
</p>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="regexp.reference.performance.html">Performance</a></div>
<div class="next" style="text-align: right; float: right;"><a href="reference.pcre.pattern.differences.html">Differences From Perl</a></div>
<div class="up"><a href="pcre.pattern.html">PCRE Patterns</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
