quotemeta()

La funzione PHP quotemeta() aggiunge un backslash davanti a ogni carattere che ha un significato speciale in un'espressione regolare, restituendo una nuova stringa "con escape". Usala quando vuoi prendere un testo arbitrario e cercarlo letteralmente all'interno di un pattern, in modo che caratteri come ., * o ( vengano trattati come testo normale invece che come operatori regex.

Questa pagina tratta la sintassi, esattamente quali caratteri vengono preceduti da escape, un esempio pratico, il problema comune con i delimitatori e quando è preferibile usare preg_quote().

Sintassi

quotemeta(string $str): string

Accetta un singolo argomento:

• $str — la stringa di input da sottoporre a escape.

Restituisce una nuova stringa con i caratteri speciali con escape. La stringa originale non viene modificata. Se $str è una stringa vuota, viene restituita una stringa vuota.

Quali caratteri vengono sottoposti a escape

quotemeta() inserisce un backslash davanti a ciascuno di questi caratteri:

.  \  +  *  ?  [  ^  ]  $  (  )

Questo è l'elenco completo. Qualsiasi carattere non presente in questo insieme — inclusi !, ,, =, -, {, } e | — viene lasciato invariato. Questa è una fonte frequente di confusione: quotemeta() non aggiunge il backslash a ogni carattere di "punteggiatura", ma solo agli undici elencati sopra.

Esempio di base

Questo produce:

Hello\^World!

Il ^ viene preceduto da escape perché è un metacarattere regex, mentre il ! viene lasciato invariato — non fa parte dell'insieme con escape.

Un esempio più completo

Per vedere il comportamento completo, applica l'escape a una stringa che contiene diversi metacaratteri:

<?php
$pattern = 'price: $9.99 (per item)*';
echo quotemeta($pattern);
?>

Output:

price: \$9\.99 \(per item\)\*

Si noti che lo spazio, i due punti e le cifre rimangono invariati, mentre $, ., (, ) e * ricevono ciascuno un backslash.

Perché usarla

Lo scopo dell'escape è di far corrispondere il testo fornito dall'utente in modo letterale. Senza escape, un termine di ricerca come a.b corrisponderebbe a axb, a-b e qualsiasi altra combinazione a + carattere + b, perché . significa "qualsiasi carattere" in una regex:

<?php
$term = 'a.b';
$haystack = 'axb';

// Unescaped: '.' acts as a wildcard and matches 'x'
var_dump((bool) preg_match("/$term/", $haystack));

// Escaped: '.' is treated literally, so it does not match
$escaped = quotemeta($term);
var_dump((bool) preg_match("/$escaped/", $haystack));
?>

Output:

bool(true)
bool(false)

quotemeta() vs preg_quote()

quotemeta() è precedente al motore PCRE di PHP e non aggiunge il backslash a ogni carattere che PCRE tratta come speciale — ad esempio ignora {, }, | e /. Inoltre non può inserire l'escape del delimitatore del pattern.

Per i pattern PCRE (preg_match(), preg_replace() e simili) è quasi sempre preferibile usare preg_quote(), che aggiunge il backslash all'intero set di metacaratteri PCRE e accetta un argomento delimitatore opzionale in modo che anche il delimitatore stesso venga preceduto da escape:

<?php
$term = 'a/b';
echo preg_quote($term, '/'); // a\/b
?>

Usa quotemeta() solo per i limitati casi in stile POSIX per cui è stata progettata; per tutto ciò che riguarda le regex nel PHP moderno, usa preg_quote().

Funzioni correlate

• preg_quote() — applica l'escape a una stringa per l'uso in un pattern PCRE (la scelta consigliata).
• preg_match() — esegue una corrispondenza con un'espressione regolare.
• preg_replace() — cerca e sostituisce usando un'espressione regolare.
• addslashes() — aggiunge il backslash a virgolette e backslash per i letterali stringa, non per le regex.

Esercitazione