Modificatori di criterio (Pattern Modifiers)

    Di seguito saranno elencati i valori attualmente previsti. I nomi posti tra parentesi si riferiscono ai corrispettivi nomi usati internamente da PCRE.

    i (PCRE_CASELESS)
    Se si attiva questo modificatore, l'espressione regolare viene riconosciuta senza distinguere tra le lettere maiuscole e minuscole.
    m (PCRE_MULTILINE)
    Per default, PCRE tratta il testo su cui fare la ricerca come una "singola linea" di caratteri (anche se in realtà può contenere diversi "a capo" (newline)). Il carattere di "inizio riga" (^) indica solamente l'inizio del testo passato. Analogamente il carattere di "fine riga" ($) indica la fine del testo o prima se vi sono dei caratteri di "a capo" (a meno che non sia attivato il modificatore D). In questo modo si comporta anche Perl. Invece quando viene indicato questo modificatore, "inizio riga" e "fine riga" vengono identificati in base ai caratteri di "a capo" presenti nel testo (rispettivamente subito dopo e subito prima di questo carattere). Questo comportamento è equivalente al modificatore /m di Perl. Se nel testo passato non vi sono caratteri di "a capo" o non vi sono occorrenze dei caratteri ^ o $ nell'espressione regolare, l'uso di questo modificatore non ha effetto.
    s (PCRE_DOTALL)
    Se si attiva questo modificatore, il carattere . usato nell'espressione regolare indica tutti i possibili caratteri compreso il carattere di "a capo" (newline). Senza questo modificatore il carattere "a capo" viene escluso. Questo modificare è equivalente a /s di Perl. Una espressione regolare contenente una forma negativa, come [^a], riconosce sempre un "a capo" a prescindere da questo modificatore.
    x (PCRE_EXTENDED)
    Se si attiva questo modificatore, verranno ignorati gli spazi presenti nell'espressione regolare, tranne quelli preceduti dal carattere di escape (\) o posti all'interno di una classe di caratteri. Saranno, inoltre, ignorati i caratteri posti tra il simbolo # (se non è preceduto dall'escape, ed è posto al di fuori di una classe di caratteri) ed il successivo carattere di "a capo" (newline). Questo comportamento equivale al flag /x di Perl e consente di inserire dei commenti all'interno di espressioni regolari complesse. Gli spazi bianchi non devono mai comparire all'interno di sequenze speciali di caratteri, come, ad esempio, la sequenza (?( che introduce ad un criterio condizionale.
    e (PREG_REPLACE_EVAL)
    Se viene specificato questo modificatore, la funzione preg_replace() attua la sostituzione dei riferimenti all'indietro nella stringa di sostituzione, la interpreta come codice PHP, quindi utilizza il risultato come testo da sostituire alle stringhe cercate. Gli apici singoli e doppi backslash (\) e i caratteri NULL sono preceduti dal backslash nei riferimenti sostituiti.
    Attenzione

    Ma funzione addslashes() viene eseguita su ogni riferimento prima che la sostituzione venga attuata. Quindi, quando il riferimento all'indietro è utilizzato come una stringa tra apici, i caratteri con escape saranno convertiti nella loro version letterale. Comunque i caratteri con escape che normalmente non sono tradotti manterranno il loro backslash. Questo rende molto complicato l'utilizzo di questo modificatore.

    Attenzione

    Assicurarsi che replacement costituisca una stringa di codice PHP valido, altrimenti PHP emetterà un errore alla linea che contiene preg_replace().

    Attenzione

    L'uso di questo modificatore non è raccomandato, dal momento che può facilmente introdurre delle vulnerabilità:

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

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

    L'esempio qui sopra può essere facilmente sfruttato passando una stringa come <h1>{${eval($_GET[php_code])}}</h1>. Questo dà all'attaccante la possibiltà di eseguire codice PHP arbitrario e ciò gli permette un access quasi totale al server.

    Per evitare questo tipo di vulnerabilità, la funzione preg_replace_callback() deve essere utilizzata al suo posto:

    <?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
    );

    Nota:

    Soltanto preg_replace() utilizza questo modificatore; le altre funzioni di PCRE lo ignorano.

    A (PCRE_ANCHORED)
    Se si specifica questo modificatore, si forza un 'ancoraggio' del criterio di ricerca. In pratica questo viene costretto a riconoscere il testo su cui si fa la ricerca solo dall'inizio. Questo effetto può essere ottenuto anche con particolari costruzioni dell'espressione regolare, che rappresentano gli unici modi utilizzabili in Perl per ottenere il medesimo scopo.
    D (PCRE_DOLLAR_ENDONLY)
    L'uso di questo modificatore forza il carattere $ dell'espressione regolare a indicare la fine della stringa oggetto della ricerca. Senza questo modificatore il carattere $ indica la posizione subito prima dell'ultimo carattere se questo è un "a capo" (ma comunque non prima di ogni altro "a capo"). Questo modificatore viene ignorato se è attivato il modificatore m. Non vi sono flag equivalenti in Perl.
    S
    Quando una espressione regolare è destinata ad essere utilizzata diverse volte, vale la pena dedicare del tempo ad ottimizzare la velocità di riconoscimento. L'uso di questo modificatore permette questa analisi. Al momento lo studio della velocità è significativo per i criteri di ricerca "non ancorati", cioè espressioni che non hanno un carattere di partenza fisso.
    U (PCRE_UNGREEDY)
    Questo modificatore inverte la "golosità" delle occorrenze, in modo da non essere golose per default, ma lo tornano ad essere se seguiti da ?. Questo flag non è compatibile con Perl. Questo comportamento può anche essere settato dalla sequenza (?U) settaggio dei modificatori all'interno del criterio di ricerca o da un punto di domanda vicino ad un quantificatore (es. .*?).

    Nota:

    Normalmente non è possibile eseguire una corrispondenza con più di pcre.backtrack_limit caratteri in modalità non golosa.

    X (PCRE_EXTRA)
    Questo modificatore attiva funzionalità addizionali di PCRE che sono incompatibili con Perl. Ogni backslash (\) posto nell'espressione regolare che non sia seguito da una lettera con significato speciale causa un errore, ciò per riservare queste sequenze a future espansioni. Per default, Perl considera il backslash (\) seguito da una lettera priva di significato speciale come un qualsiasi testo. Al momento non vi sono altre caratteristiche gestite tramite questo modificatore.
    J (PCRE_INFO_JCHANGED)
    L'opzione di configurazione interna (?J) cambia l'opzione locale PCRE_DUPNAMES Permette la duplicazione dei nomi per le sottoregole.
    u (PCRE_UTF8)
    Questo modificatore attiva funzionalità di PCRE che sono incompatibili con Perl. Le stringhe di ricerca sono considerate come UTF-8. Questo modificatore è disponibile dalla versione 4.1.0 di PHP di Unix e dalla versione 4.2.3 sulla piattaforma win32. La validità UTF-8 della regola è controllata da PHP 4.3.5.

    Improve This Page

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    ＋add a note

    User Contributed Notes 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
    ＋add a note
    To Top