quotemeta()

Die PHP-Funktion quotemeta() fügt vor jedem Zeichen, das in einem regulären Ausdruck eine besondere Bedeutung hat, einen Backslash ein und gibt einen neuen „maskierten" String zurück. Verwenden Sie sie, wenn Sie einen beliebigen Text nehmen und ihn wörtlich in einem Muster suchen möchten, sodass Zeichen wie ., * oder ( als einfacher Text und nicht als Regex-Operatoren behandelt werden.

Diese Seite behandelt die Syntax, genau welche Zeichen maskiert werden, ein Anwendungsbeispiel, die häufige Falle bei Trennzeichen und wann Sie stattdessen die besser geeignete Funktion preg_quote() verwenden sollten.

Syntax

quotemeta(string $str): string

Sie nimmt ein einziges Argument entgegen:

• $str — der zu maskierende Eingabe-String.

Sie gibt einen neuen String mit den maskierten Sonderzeichen zurück. Der ursprüngliche String wird nicht verändert. Wenn $str ein leerer String ist, wird ein leerer String zurückgegeben.

Welche Zeichen werden maskiert

quotemeta() setzt einen Backslash vor jedes dieser Zeichen:

.  \  +  *  ?  [  ^  ]  $  (  )

Das ist die vollständige Liste. Alles, was nicht in dieser Menge enthalten ist — einschließlich !, ,, =, -, {, } und | — wird unverändert gelassen. Dies ist eine häufige Quelle der Verwirrung: quotemeta() maskiert nicht jedes „Satzzeichen", sondern nur die elf oben aufgeführten Zeichen.

Grundlegendes Beispiel

Dies ergibt:

Hello\^World!

Das ^ wird maskiert, weil es ein Regex-Metazeichen ist, während das ! unverändert bleibt — es ist nicht in der maskierten Menge enthalten.

Ein vollständigeres Beispiel

Um das vollständige Verhalten zu sehen, maskieren Sie einen String, der mehrere Metazeichen enthält:

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

Ausgabe:

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

Beachten Sie, dass das Leerzeichen, der Doppelpunkt und die Ziffern unverändert bleiben, während $, ., (, ) und * jeweils einen Backslash erhalten.

Warum man es verwenden würde

Der Zweck der Maskierung besteht darin, vom Benutzer eingegebenen Text wörtlich zu suchen. Ohne Maskierung würde ein Suchbegriff wie a.b auf axb, a-b und jedes andere a + Zeichen + b passen, weil . in einem Regex „beliebiges Zeichen" bedeutet:

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

Ausgabe:

bool(true)
bool(false)

quotemeta() vs preg_quote()

quotemeta() stammt aus der Zeit vor PHPs PCRE-Engine und maskiert nicht jedes Zeichen, das PCRE als Sonderzeichen behandelt — zum Beispiel ignoriert es {, }, | und /. Es kann auch Ihr Mustertrennzeichen nicht maskieren.

Für PCRE-Muster (preg_match(), preg_replace() und verwandte Funktionen) sollten Sie fast immer preg_quote() bevorzugen, das den vollständigen PCRE-Metazeichensatz maskiert und ein optionales Trennzeichen-Argument akzeptiert, sodass das Trennzeichen selbst ebenfalls maskiert wird:

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

Greifen Sie auf quotemeta() nur für die eingeschränkten POSIX-ähnlichen Fälle zurück, für die es entwickelt wurde; für alles Regex-bezogene in modernem PHP verwenden Sie preg_quote().

Verwandte Funktionen

• preg_quote() — maskiert einen String für die Verwendung in einem PCRE-Muster (die empfohlene Wahl).
• preg_match() — führt einen regulären Ausdrucks-Abgleich durch.
• preg_replace() — suchen und ersetzen mit einem regulären Ausdruck.
• addslashes() — maskiert Anführungszeichen und Backslashes für String-Literale, nicht für reguläre Ausdrücke.

Übung