quotemeta()

La función quotemeta() de PHP añade una barra invertida antes de cada carácter que tiene un significado especial en una expresión regular, devolviendo una nueva cadena "escapada". Úsala cuando quieras tomar un fragmento de texto arbitrario y hacer coincidir literalmente dentro de un patrón, de modo que caracteres como ., * o ( se traten como texto plano en lugar de operadores de expresiones regulares.

Esta página cubre la sintaxis, exactamente qué caracteres se escapan, un ejemplo práctico, el error habitual relacionado con los delimitadores, y cuándo es mejor usar preg_quote().

Sintaxis

quotemeta(string $str): string

Acepta un único argumento:

• $str — la cadena de entrada a escapar.

Devuelve una nueva cadena con los caracteres especiales escapados. La cadena original no se modifica. Si $str es una cadena vacía, se devuelve una cadena vacía.

Qué caracteres se escapan

quotemeta() coloca una barra invertida delante de cada uno de estos caracteres:

.  \  +  *  ?  [  ^  ]  $  (  )

Esa es la lista completa. Cualquier otro carácter que no esté en este conjunto — incluyendo !, ,, =, -, {, } y | — se deja sin cambios. Esta es una fuente frecuente de confusión: quotemeta() no escapa todos los caracteres de "puntuación", solo los once listados anteriormente.

Ejemplo básico

Esto produce:

Hello\^World!

El ^ se escapa porque es un metacarácter de expresión regular, mientras que ! se deja solo, ya que no forma parte del conjunto de caracteres escapados.

Un ejemplo más completo

Para ver el comportamiento completo, escapa una cadena que contenga varios metacaracteres:

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

Salida:

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

Observa que el espacio, los dos puntos y los dígitos no cambian, mientras que $, ., (, ) y * obtienen cada uno una barra invertida.

Por qué usarla

El propósito de escapar es hacer coincidir texto suministrado por el usuario de forma literal. Sin escapar, un término de búsqueda como a.b coincidiría con axb, a-b y cualquier otro a + carácter + b, porque . significa "cualquier carácter" en una expresión regular:

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

Salida:

bool(true)
bool(false)

quotemeta() vs preg_quote()

quotemeta() es anterior al motor PCRE de PHP y no escapa todos los caracteres que PCRE trata como especiales — por ejemplo, ignora {, }, | y /. Tampoco puede escapar el delimitador de tu patrón.

Para patrones PCRE (preg_match(), preg_replace() y similares) casi siempre deberías preferir preg_quote(), que escapa el conjunto completo de metacaracteres PCRE y acepta un argumento opcional de delimitador para que el delimitador en sí también se escape:

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

Recurre a quotemeta() solo para los casos de estilo POSIX limitados para los que fue diseñada; para todo lo relacionado con expresiones regulares en PHP moderno, usa preg_quote().

Funciones relacionadas

• preg_quote() — escapa una cadena para su uso en un patrón PCRE (la opción recomendada).
• preg_match() — realiza una coincidencia con expresión regular.
• preg_replace() — busca y reemplaza usando una expresión regular.
• addslashes() — escapa comillas y barras invertidas para literales de cadena, no para expresiones regulares.

Práctica