PHP 7.0.6 Released

    Pattern Modifiers

    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.

    i (PCRE_CASELESS)
    If this modifier is set, letters in the pattern match both upper and lower case letters.
    m (PCRE_MULTILINE)
    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 D modifier is set). This is the same as Perl. 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.
    s (PCRE_DOTALL)
    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.
    x (PCRE_EXTENDED)
    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.
    e (PREG_REPLACE_EVAL)
    Warning

    This feature was DEPRECATED in PHP 5.5.0, and REMOVED as of PHP 7.0.0.

    If this deprecated modifier is set, preg_replace() 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 (\) and NULL chars will be escaped by backslashes in substituted backreferences.
    Caution

    The addslashes() 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.

    Caution

    Make sure that replacement constitutes a valid PHP code string, otherwise PHP will complain about a parse error at the line containing preg_replace().

    Caution

    Use of this modifier is discouraged, as it can easily introduce security vulnerabilites:

    <?php
    $html     = $_POST['html'];

    // uppercase headings
    $html = preg_replace(
            '(<h([1-6])>(.*?)</h\1>)e',
            '"<h$1>" . strtoupper("$2") . "</h$1>"',
            $html
    );

    The above example code can be easily exploited by passing in a string such as <h1>{${eval($_GET[php_code])}}</h1>. This gives the attacker the ability to execute arbitrary PHP code and as such gives him nearly complete access to your server.

    To prevent this kind of remote code execution vulnerability the preg_replace_callback() function should be used instead:

    <?php
    $html     = $_POST['html'];

    // uppercase headings
    $html = preg_replace_callback(
            '(<h([1-6])>(.*?)</h\1>)',
        function (    $m) {
            return     "<h$m[1]>" . strtoupper($m[2]) . "</h$m[1]>";
        },
            $html
    );

    Note:

    Only preg_replace() uses this modifier; it is ignored by other PCRE functions.

    A (PCRE_ANCHORED)
    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.
    D (PCRE_DOLLAR_ENDONLY)
    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 m modifier is set. There is no equivalent to this modifier in Perl.
    S
    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.
    U (PCRE_UNGREEDY)
    This modifier inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by ?. It is not compatible with Perl. It can also be set by a (?U) modifier setting within the pattern or by a question mark behind a quantifier (e.g. .*?).

    Note:

    It is usually not possible to match more than pcre.backtrack_limit characters in ungreedy mode.

    X (PCRE_EXTRA)
    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.
    J (PCRE_INFO_JCHANGED)
    The (?J) internal option setting changes the local PCRE_DUPNAMES option. Allow duplicate names for subpatterns.
    u (PCRE_UTF8)
    This modifier turns on additional functionality of PCRE that is incompatible with Perl. Pattern and subject 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 and the subject is checked since PHP 4.3.5. An invalid subject will cause the preg_* function to match nothing; an invalid pattern will trigger an error of level E_WARNING. Five and six octet UTF-8 sequences are regarded as invalid since PHP 5.3.4 (resp. PCRE 7.3 2007-08-28); formerly those have been regarded as valid UTF-8.

    User Contributed Notes

    hfuecks at nospam dot org
    10 years ago
    Regarding the validity of a UTF-8 string when using the /u pattern modifier, some things to be aware of;

    1. If the pattern itself contains an invalid UTF-8 character, you get an error (as mentioned in the docs above - "UTF-8 validity of the pattern is checked since PHP 4.3.5"

    2. When the subject string contains invalid UTF-8 sequences / codepoints, it basically result in a "quiet death" for the preg_* functions, where nothing is matched but without indication that the string is invalid UTF-8

    3. PCRE regards five and six octet UTF-8 character sequences as valid (both in patterns and the subject string) but these are not supported in Unicode ( see section 5.9 "Character Encoding" of the "Secure Programming for Linux and Unix HOWTO" - can be found at http://www.tldp.org/ and other places )

    4. For an example algorithm in PHP which tests the validity of a UTF-8 string (and discards five / six octet sequences) head to: http://hsivonen.iki.fi/php-utf8/

    The following script should give you an idea of what works and what doesn't;

    <?php
    $examples     = array(
            'Valid ASCII' => "a",
            'Valid 2 Octet Sequence' => "\xc3\xb1",
            'Invalid 2 Octet Sequence' => "\xc3\x28",
            'Invalid Sequence Identifier' => "\xa0\xa1",
            'Valid 3 Octet Sequence' => "\xe2\x82\xa1",
            'Invalid 3 Octet Sequence (in 2nd Octet)' => "\xe2\x28\xa1",
            'Invalid 3 Octet Sequence (in 3rd Octet)' => "\xe2\x82\x28",

            'Valid 4 Octet Sequence' => "\xf0\x90\x8c\xbc",
            'Invalid 4 Octet Sequence (in 2nd Octet)' => "\xf0\x28\x8c\xbc",
            'Invalid 4 Octet Sequence (in 3rd Octet)' => "\xf0\x90\x28\xbc",
            'Invalid 4 Octet Sequence (in 4th Octet)' => "\xf0\x28\x8c\x28",
            'Valid 5 Octet Sequence (but not Unicode!)' => "\xf8\xa1\xa1\xa1\xa1",
            'Valid 6 Octet Sequence (but not Unicode!)' => "\xfc\xa1\xa1\xa1\xa1\xa1",
    );

    echo     "++Invalid UTF-8 in pattern\n";
    foreach (     $examples as $name => $str ) {
        echo     "$name\n";
            preg_match("/".$str."/u",'Testing');
    }

    echo     "++ preg_match() examples\n";
    foreach (     $examples as $name => $str ) {
       
            preg_match("/\xf8\xa1\xa1\xa1\xa1/u", $str, $ar);
        echo     "$name: ";

        if (     count($ar) == 0 ) {
            echo     "Matched nothing!\n";
        } else {
            echo     "Matched {$ar[0]}\n";
        }
       
    }

    echo     "++ preg_match_all() examples\n";
    foreach (     $examples as $name => $str ) {
            preg_match_all('/./u', $str, $ar);
        echo     "$name: ";
       
            $num_utf8_chars = count($ar[0]);
        if (     $num_utf8_chars == 0 ) {
            echo     "Matched nothing!\n";
        } else {
            echo     "Matched $num_utf8_chars character\n";
        }
       
    }
    ?>
    michal dot kocarek at brainbox dot cz
    6 years ago
    In case you're wondering, what is the meaning of "S" modifier, this paragraph might be useful:

    When "S" modifier is set, PHP calls the pcre_study() function from the PCRE API before executing the regexp. Result from the function is passed directly to pcre_exec().

    For more information about pcre_study() and "Studying the pattern" check the PCRE manual on http://www.pcre.org/pcre.txt

    PS: Note that function names "pcre_study" and "pcre_exec" used here refer to PCRE library functions written in C language and not to any PHP functions.
    phpman at crustynet dot org dot uk
    5 years ago
    The description of the "u" flag is a bit misleading. It suggests that it is only required if the pattern contains UTF-8 characters, when in fact it is required if either the pattern or the subject contain UTF-8. Without it, I was having problems with preg_match_all returning invalid multibyte characters when given a UTF-8 subject string.

    It's fairly clear if you read the documentation for libpcre:

           In  order  process  UTF-8 strings, you must build PCRE to include UTF-8
           support in the code, and, in addition,  you  must  call  pcre_compile()
           with  the  PCRE_UTF8  option  flag,  or the pattern must start with the
           sequence (*UTF8). When either of these is the case,  both  the  pattern
           and  any  subject  strings  that  are matched against it are treated as
           UTF-8 strings instead of strings of 1-byte characters.

    [from http://www.pcre.org/pcre.txt]
    Daniel Klein
    4 years ago
    If the _subject_ contains utf-8 sequences the 'u' modifier should be set, otherwise a pattern such as /./ could match a utf-8 sequence as two to four individual ASCII characters. It is not a requirement, however, as you may have a need to break apart utf-8 sequences into single bytes. Most of the time, though, if you're working with utf-8 strings you should use the 'u' modifier.

    If the subject doesn't contain any utf-8 sequences (i.e. characters in the range 0x00-0x7F only) but the pattern does, as far as I can work out, setting the 'u' modifier would have no effect on the result.
    varrah NO_GARBAGE_OR_SPAM AT mail DOT ru
    10 years ago
    Spent a few days, trying to understand how to create a pattern for Unicode chars, using the hex codes. Finally made it, after reading several manuals, that weren't giving any practical PHP-valid examples. So here's one of them:

    For example we would like to search for Japanese-standard circled numbers 1-9 (Unicode codes are 0x2460-0x2468) in order to make it through the hex-codes the following call should be used:
    preg_match('/[\x{2460}-\x{2468}]/u', $str);

    Here $str is a haystack string
    \x{hex} - is an UTF-8 hex char-code
    and /u is used for identifying the class as a class of Unicode chars.

    Hope, it'll be useful.
    ebarnard at marathonmultimedia dot com
    9 years ago
    When adding comments with the /x modifier, don't use the pattern delimiter in the comments. It may not be ignored in the comments area. Example:

    <?php
    $target     = 'some text';
    if(    preg_match('/
                    e # Comments here
                   /x'    ,$target)) {
        print     "Target 1 hit.\n";
    }
    if(    preg_match('/
                    e # /Comments here with slash
                   /x'    ,$target)) {
        print     "Target 1 hit.\n";
    }
    ?>

    prints "Target 1 hit." but then generates a PHP warning message for the second preg_match():

    Warning:  preg_match() [function.preg-match]: Unknown modifier 'C' in /ebarnard/x-modifier.php on line 11
    To Top