quotemeta()

A função PHP quotemeta() adiciona uma barra invertida antes de cada caractere que tem um significado especial em uma expressão regular, retornando uma nova string "escapada". Use-a quando quiser pegar um trecho arbitrário de texto e combiná-lo literalmente dentro de um padrão, de modo que caracteres como ., * ou ( sejam tratados como texto simples em vez de operadores de regex.

Esta página cobre a sintaxe, exatamente quais caracteres são escapados, um exemplo prático, a armadilha comum em torno dos delimitadores e quando recorrer ao preg_quote(), que é mais adequado.

Sintaxe

quotemeta(string $str): string

Ela recebe um único argumento:

• $str — a string de entrada a ser escapada.

Ela retorna uma nova string com os caracteres especiais escapados. A string original não é modificada. Se $str for uma string vazia, uma string vazia é retornada.

Quais caracteres são escapados

quotemeta() coloca uma barra invertida à frente de cada um destes caracteres:

.  \  +  *  ?  [  ^  ]  $  (  )

Essa é a lista completa. Qualquer coisa que não esteja neste conjunto — incluindo !, ,, =, -, {, } e | — é deixada intocada. Esta é uma fonte frequente de confusão: quotemeta() não escapa todos os caracteres de "pontuação", apenas os onze listados acima.

Exemplo básico

Isso produz:

Hello\^World!

O ^ é escapado porque é um metacaractere de regex, enquanto ! é deixado sozinho — ele não está no conjunto escapado.

Um exemplo mais completo

Para ver o comportamento completo, escape uma string que contém vários metacaracteres:

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

Saída:

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

Observe que o espaço, os dois-pontos e os dígitos não são alterados, enquanto $, ., (, ) e * ganham cada um uma barra invertida.

Por que você usaria isso

O objetivo do escape é combinar texto fornecido pelo usuário literalmente. Sem escape, um termo de busca como a.b corresponderia a axb, a-b e qualquer outro a + caractere + b, porque . significa "qualquer caractere" em uma 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));
?>

Saída:

bool(true)
bool(false)

quotemeta() vs preg_quote()

quotemeta() é anterior ao motor PCRE do PHP e não escapa todos os caracteres que o PCRE trata como especiais — por exemplo, ignora {, }, | e /. Também não consegue escapar o delimitador do seu padrão.

Para padrões PCRE (preg_match(), preg_replace() e similares), você quase sempre deve preferir preg_quote(), que escapa o conjunto completo de metacaracteres PCRE e aceita um argumento de delimitador opcional para que o próprio delimitador também seja escapado:

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

Recorra a quotemeta() apenas para os casos limitados de estilo POSIX para os quais foi projetada; para tudo relacionado a regex no PHP moderno, use preg_quote().

Funções relacionadas

• preg_quote() — escapa uma string para uso em um padrão PCRE (a escolha recomendada).
• preg_match() — realiza uma correspondência com expressão regular.
• preg_replace() — busca e substitui usando uma expressão regular.
• addslashes() — escapa aspas e barras invertidas para literais de string, não para regexes.

Prática