PHP 8.4.1 Released!

    模式修饰符

    目前可用的 PCRE 修饰符如下所示。括号中的名称是这些修饰符的内部 PCRE 名称。 修饰符中的空格和换行符会被忽略，其他字符会引发错误。

    i (PCRE_CASELESS)
    如果设置了这个修饰符，模式中的字母会匹配大小写字母。
    m (PCRE_MULTILINE)
    默认情况下，PCRE 将主题字符串视为由单个 "行" 字符组成的字符串（即使实际上包含多个换行符）。 "行首" 元字符 (^) 仅在字符串的开头匹配，而 "行尾" 元字符 ($) 仅在字符串的结尾或终止换行符之前匹配 （除非设置了 D 修饰符）。 这与 Perl 相同。 当设置了这个修饰符时，"行首" 和 "行尾" 元字符会在主题字符串中的每个换行符之后或之前立即匹配。 这等效于 Perl 的 /m 修饰符。如果主题字符串中没有 "\n" 字符，或者模式中没有 "^" 或 "$" 的出现， 设置这个修饰符不会产生任何效果。
    s (PCRE_DOTALL)
    如果设置了这个修饰符，模式中的点元字符将匹配所有字符，包括换行符。如果没有设置这个修饰符， 换行符会被排除在外。这个修饰符等效于 Perl 的 /s 修饰符。负类（如 [^a]）总是匹配换行符， 与这个修饰符的设置无关。
    x (PCRE_EXTENDED)
    如果设置了这个修饰符，模式中的空白数据字符会被完全忽略，除非被转义或在字符类内部， 并且在一个未转义的 "#" 和下一个换行符之间的字符也会被忽略。这等效于 Perl 的 /x 修饰符， 并且使得在复杂模式中包含评论成为可能。然而，这仅适用于数据字符。空白字符永远不会出现在模式中的特殊字符序列中， 例如在引入条件子模式的序列 (?( 中。
    A (PCRE_ANCHORED)
    如果设置了这个修饰符，模式会被强制为 "锚定"，也就是说，它只能匹配主题字符串的开头。 这个效果也可以通过模式本身中的适当构造来实现，这是在 Perl 中唯一的方法。
    D (PCRE_DOLLAR_ENDONLY)
    如果设置了这个修饰符，模式中的美元元字符只能匹配主题字符串的结尾。 如果没有设置这个修饰符，美元元字符也会在主题字符串的最后一个字符之前立即匹配，但不会在其他换行符之前匹配。 如果设置了 m 修饰符，这个修饰符会被忽略。在 Perl 中没有这个修饰符的等效项。
    S
    当一个模式将被多次使用时，值得花费更多时间来分析它，以加快匹配所需的时间。 如果设置了这个修饰符，那么会执行额外的分析。 目前，对于不具有单个固定起始字符的非锚定模式，研究模式是有用的。 从 PHP 7.3.0 开始，这个修饰符没有效果。
    U (PCRE_UNGREEDY)
    这个修饰符反转了量词的 "贪婪性"，使其默认情况下不贪婪，但如果后面跟着 ?，则变为贪婪。 它与 Perl 不兼容。也可以通过模式内的 (?U)修饰符设置 或在量词后面加上问号（例如 .*?）来设置。

    注意:

    在不贪婪模式下，通常不可能匹配超过 pcre.backtrack_limit 个字符。

    X (PCRE_EXTRA)
    这个修饰符打开了 PCRE 的额外功能，这些功能与 Perl 不兼容。模式中的任何反斜杠后跟一个没有特殊含义的字母的组合都会引发错误， 从而为将来的扩展保留这些组合。默认情况下，与 Perl 一样，反斜杠后跟一个没有特殊含义的字母会被视为字面量。 目前没有其他受这个修饰符控制的功能。
    J (PCRE_INFO_JCHANGED)
    这个内部修饰符 (?J) 改变了本地 PCRE_DUPNAMES 选项。 允许子模式名称重复。 从 PHP 7.2.0 开始，J 也作为修饰符支持。
    u (PCRE_UTF8)
    这个修饰符打开了 PCRE 的额外功能，这些功能与 Perl 不兼容。模式和主题字符串被视为 UTF-8。 无效的主题字符串会导致 preg_* 函数匹配不到任何内容；无效的模式会触发一个 E_WARNING 级别的错误。 五个和六个字节的 UTF-8 序列被视为无效。
    n (PCRE_NO_AUTO_CAPTURE)
    这个修饰符使简单的 (xyz) 组不捕获。 只有像 (?<name>xyz) 这样的命名组才会捕获。 这只影响哪些组是捕获的，仍然可以使用编号的子模式引用，匹配数组仍然包含编号的结果。 从 PHP 8.2.0 开始可用。

    改进此页面

    了解如何改进此页面 • 提交拉取请求 • 报告一个错误
    ＋添加备注

    用户贡献的备注 11 notes

    up
    27
    hfuecks at nospam dot org
    19 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";
    }

    }
    ?>
    up
    13
    varrah NO_GARBAGE_OR_SPAM AT mail DOT ru
    19 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.
    up
    11
    phpman at crustynet dot org dot uk
    13 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]
    up
    7
    arash dot dalir at gmail dot com
    7 years ago
    the PCRE_INFO_JCHANGED modifier is apparently not accepted as a global option (after the closing delimiter) in PHP versions <= 5.4 (not checked in PHP 5.5) but allowed in PHP 5.6 (also not checked in PHP 7.X)

    The following pattern doesn't work in PHP 5.4, but it works in PHP 5.6:

    <?php
    //test.php
    preg_match_all('/(?<dup_name>\d{1,4})\-(?<dup_name>\d{1,2})/J', '1234-23', $matches);
    var_dump($matches);

    /*
    output in PHP 5.4:
    Warning: preg_match_all(): Unknown modifier 'J' in test.php on line 3
    NULL
    --------------
    output PHP 5.6:
    array(4) {
    [0]=> array(1) { [0]=> string(7) "1234-23" }
    ["dup_name"]=> array(1) { [0]=> string(2) "23" }
    [1]=> array(1) { [0]=> string(4) "1234" }
    [2]=> array(1) { [0]=> string(2) "23" }
    }
    */
    ?>

    in order to resolve this issue in PHP 5.4, one can use the (?J) pattern modifier, which indicates the pattern (from that point forward) allows duplicate names for subpatterns.

    code which works in PHP 5.4:
    <?php

    preg_match_all    ('/(?J)(?<dup_name>\d{1,4})\-(?<dup_name>\d{1,2})/', '1234-23', $matches);
    var_dump($matches);

    /*
    output in PHP 5.4:
    array(4) {
    [0]=> array(1) { [0]=> string(7) "1234-23" }
    ["dup_name"]=> array(1) { [0]=> string(2) "23" }
    [1]=> array(1) { [0]=> string(4) "1234" }
    [2]=> array(1) { [0]=> string(2) "23" }
    }
    --------------
    output in PHP 5.6 (the same as with /J):
    array(4) {
    [0]=> array(1) { [0]=> string(7) "1234-23" }
    ["dup_name"]=> array(1) { [0]=> string(2) "23" }
    [1]=> array(1) { [0]=> string(4) "1234" }
    [2]=> array(1) { [0]=> string(2) "23" }
    }
    */
    ?>
    up
    4
    Hayley Watson
    4 years ago
    Starting from 7.3.0, the 'S' modifier has no effect; this analysis is now always done by the PCRE engine.
    up
    10
    Daniel Klein
    12 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.
    up
    2
    Anonymous
    5 years ago
    A warning about the /i modifier and POSIX character classes:
    If you're using POSIX character classes in your regex that indicate case such as [:upper:] or [:lower:] in combination with the /i modifier, then in PHP < 7.3 the /i modifier will take precedence and effectively make both those character classes work as [:alpha:], but in PHP >= 7.3 the character classes overrule the /i modifier.
    up
    2
    Wirek
    6 years ago
    A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end ($) of any line in multiple lines mode (/m).
    <?php
    // Various OS-es have various end line (a.k.a line break) chars:
    // - Windows uses CR+LF (\r\n);
    // - Linux LF (\n);
    // - OSX CR (\r).
    // And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?).
    $str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
    // C 3 p 0 _
    $pat1='/\w$/mi'; // This works excellent in JavaScript (Firefox 7.0.1+)
    $pat2='/\w\r?$/mi';
    $pat3='/\w\R?$/mi'; // Somehow disappointing according to php.net and pcre.org
    $pat4='/\w\v?$/mi';
    $pat5='/(*ANYCRLF)\w$/mi'; // Excellent but undocumented on php.net at the moment
    $n=preg_match_all($pat1, $str, $m1);
    $o=preg_match_all($pat2, $str, $m2);
    $p=preg_match_all($pat3, $str, $m3);
    $r=preg_match_all($pat4, $str, $m4);
    $s=preg_match_all($pat5, $str, $m5);
    echo     $str."\n1 !!! $pat1 ($n): ".print_r($m1[0], true)
    .    "\n2 !!! $pat2 ($o): ".print_r($m2[0], true)
    .    "\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    .    "\n4 !!! $pat4 ($r): ".print_r($m4[0], true)
    .    "\n5 !!! $pat5 ($s): ".print_r($m5[0], true);
    // Note the difference among the three very helpful escape sequences in $pat2 (\r), $pat3 (\R), $pat4 (\v) and altered newline option in $pat5 ((*ANYCRLF)) - for some applications at least.

    /* The code above results in the following output:
    ABC ABC

    123 123
    def def
    nop nop
    890 890
    QRS QRS

    ~-_ ~-_
    1 !!! /\w$/mi (3): Array
    (
    [0] => C
    [1] => 0
    [2] => _
    )

    2 !!! /\w\r?$/mi (5): Array
    (
    [0] => C
    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
    )

    3 !!! /\w\R?$/mi (5): Array
    (
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
    )

    4 !!! /\w\v?$/mi (5): Array
    (
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
    )

    5 !!! /(*ANYCRLF)\w$/mi (7): Array
    (
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
    [6] => _
    )
    */
    ?>
    Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
    up
    1
    Wirek
    6 years ago
    An important addendum (with new $pat3_2 utilising \R properly, its results and comments):
    Note that there are (sometimes difficult to grasp at first glance) nuances of meaning and application of escape sequences like \r, \R and \v - none of them is perfect in all situations, but they are quite useful nevertheless. Some official PCRE control options and their changes come in handy too - unfortunately neither (*ANYCRLF), (*ANY) nor (*CRLF) is documented here on php.net at the moment (although they seem to be available for over 10 years and 5 months now), but they are described on Wikipedia ("Newline/linebreak options" at https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) and official PCRE library site ("Newline convention" at http://www.pcre.org/original/doc/html/pcresyntax.html#SEC17) pretty well. The functionality of \R appears somehow disappointing (with default configuration of compile time option) according to php.net as well as official description ("Newline sequences" at https://www.pcre.org/original/doc/html/pcrepattern.html#newlineseq) when used improperly.

    A hint for those of you who are trying to fight off (or work around at least) the problem of matching a pattern correctly at the end (or at the beginning) of any line even without the multiple lines mode (/m) or meta-character assertions ($ or ^).
    <?php
    // Various OS-es have various end line (a.k.a line break) chars:
    // - Windows uses CR+LF (\r\n);
    // - Linux LF (\n);
    // - OSX CR (\r).
    // And that's why single dollar meta assertion ($) sometimes fails with multiline modifier (/m) mode - possible bug in PHP 5.3.8 or just a "feature"(?) of default configuration option for meta-character assertions (^ and $) at compile time of PCRE.
    $str="ABC ABC\n\n123 123\r\ndef def\rnop nop\r\n890 890\nQRS QRS\r\r~-_ ~-_";
    // C 3 p 0 _
    $pat3='/\w\R?$/mi'; // Somehow disappointing according to php.net and pcre.org when used improperly
    $pat3_2='/\w(?=\R)/i'; // Much better with allowed lookahead assertion (just to detect without capture) without multiline (/m) mode; note that with alternative for end of string ((?=\R|$)) it would grab all 7 elements as expected, but '/(*ANYCRLF)\w$/mi' is more straightforward in use anyway
    $p=preg_match_all($pat3, $str, $m3);
    $r=preg_match_all($pat3_2, $str, $m4);
    echo     $str."\n3 !!! $pat3 ($p): ".print_r($m3[0], true)
    .    "\n3_2 !!! $pat3_2 ($r): ".print_r($m4[0], true);
    // Note the difference between the two very helpful escape sequences in $pat3 and $pat3_2 (\R) - for some applications at least.

    /* The code above results in the following output:
    ABC ABC

    123 123
    def def
    nop nop
    890 890
    QRS QRS

    ~-_ ~-_
    3 !!! /\w\R?$/mi (5): Array
    (
    [0] => C

    [1] => 3
    [2] => p
    [3] => 0
    [4] => _
    )

    3_2 !!! /\w(?=\R)/i (6): Array
    (
    [0] => C
    [1] => 3
    [2] => f
    [3] => p
    [4] => 0
    [5] => S
    )
    */
    ?>
    Unfortunately, I haven't got any access to a server with the latest PHP version - my local PHP is 5.3.8 and my public host's PHP is version 5.2.17.
    up
    2
    michal dot kocarek at brainbox dot cz
    15 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.
    up
    2
    ebarnard at marathonmultimedia dot com
    17 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