PHP-String-Funktion addcslashes()

Die Funktion addcslashes() gibt einen string zurück, bei dem vor jedem Zeichen der angegebenen „Zeichenliste" ein Backslash (\) eingefügt wird. Der Name leitet sich vom C-Style-Escaping ab: Im Gegensatz zu addslashes(), das immer nur die vier festen Zeichen ', ", \ und NUL escapet, können Sie mit addcslashes() selbst bestimmen, welche Zeichen escaped werden.

Diese Seite behandelt die Syntax, das Escapen einzelner Zeichen und ganzer Bereiche, häufige Fallstricke sowie die Frage, wann addcslashes() gegenüber einer sichereren Alternative vorzuziehen ist.

Syntax

addcslashes(string $string, string $characters): string

Die Funktion nimmt zwei Parameter entgegen, die beide erforderlich sind:

• $string — der zu verarbeitende Eingabe-string.
• $characters — die Liste der zu escapenden Zeichen. Zeichen können einzeln angegeben werden ("W3d") oder als Bereich mit .. ("a..z").

Rückgabewert

Die Funktion gibt einen neuen string zurück, bei dem vor jedem Zeichen, das in $characters vorkommt, ein Backslash eingefügt wird. Der ursprüngliche string wird nicht verändert, da strings in PHP per Wert übergeben werden.

Beachten Sie, dass einige Zeichen im C-Stil und nicht mit einem wörtlichen Backslash escaped werden: Zeichen mit ASCII-Codes 32 und darunter oder 127 und darüber werden in ihre C-Escape-Sequenz umgewandelt (ein Zeilenumbruch wird z. B. zu \n, ein Tabulator zu \t, und andere Steuerzeichen werden oktal dargestellt wie \037).

Einzelne Zeichen escapen

Die einfachste Verwendung besteht darin, die gewünschten Zeichen einzeln aufzulisten.

Beispiel 1

Ausgabe:

Hello\, World!

Nur das Komma war in der Zeichenliste, daher erhält nur das Komma einen vorangestellten Backslash.

Beispiel 2

Mehrere Zeichen können gleichzeitig aufgelistet werden. Jedes Vorkommen eines beliebigen aufgelisteten Zeichens wird escaped, und die Zuordnung ist Groß-/Kleinschreibungssensitiv — das Escapen von "W" hat keine Auswirkung auf das kleingeschriebene "w".

Ausgabe:

\Websites like \W\3\docs are a great resource for learning PHP.

Beide "W"-Zeichen, die "3" und das "d" wurden jeweils mit einem Backslash vorangestellt. Die Kleinbuchstaben blieben unverändert.

Einen Zeichenbereich escapen

Um eine zusammenhängende Folge von Zeichen zu escapen, geben Sie Anfang und Ende durch .. getrennt an. Zum Beispiel escaped "A..Z" jeden Großbuchstaben und "0..9" jede Ziffer:

<?php

$string = "Price: 25 USD";

// escape every digit 0–9
$escaped_string = addcslashes($string, "0..9");

echo $escaped_string;

?>

Ausgabe:

Price: \2\5 USD

Der Bereich muss aufsteigend sein. Das Schreiben von "z..a" (absteigend) erzeugt nicht den Bereich a bis z; PHP gibt eine Warnung aus und behandelt die Punkte stattdessen wörtlich. Setzen Sie immer den niedrigeren Codepunkt zuerst.

Häufige Fallstricke

• Das Escapen von \0, \r, \n, \t ist gefährlich. Diese Zeichen haben eine besondere Bedeutung in C-Escape-Sequenzen. Wenn Sie sie in $characters übergeben, können Zeichen auf unbeabsichtigte Weise umgewandelt werden — vermeiden Sie dies, wenn Sie nicht genau wissen, was Sie tun.
• Die Zuordnung unterscheidet Groß- und Kleinschreibung. Geben Sie beide Varianten an (z. B. "Ww" oder den Bereich "A..z"), wenn Sie beide abdecken möchten.
• Der ursprüngliche string bleibt unverändert. addcslashes() gibt einen neuen string zurück; denken Sie daran, den Rückgabewert zuzuweisen oder zu verwenden.

Wann es einzusetzen ist

Greifen Sie auf addcslashes() zurück, wenn Sie eine benutzerdefinierte Menge von Zeichen escapen müssen — zum Beispiel beim Erstellen eines strings für ein System, das bestimmte Zeichen besonders behandelt. Für die gängige Aufgabe, Anführungszeichen und Backslashes für die veraltete String-Verarbeitung zu escapen, verwenden Sie stattdessen addslashes(). Um Zeichen für reguläre Ausdrücke zu escapen, verwenden Sie quotemeta(), und um Benutzereingaben für die HTML-Ausgabe sicher zu machen, verwenden Sie htmlspecialchars().

Um das von addcslashes() angewandte Escaping rückgängig zu machen, verwenden Sie stripcslashes().

Wichtig: addcslashes() ist kein Sicherheitsmerkmal. Verlassen Sie sich niemals darauf, um SQL-Injection zu verhindern oder HTML zu bereinigen — verwenden Sie für diese Aufgaben Prepared Statements und htmlspecialchars().

Fazit

Die Funktion addcslashes() escaped eine benutzerdefinierte Menge von Zeichen in einem string nach C-Style-Regeln und gibt Ihnen damit mehr Kontrolle als addslashes(). Listen Sie die Zeichen einzeln oder als aufsteigenden ..-Bereich auf, denken Sie daran, dass die Zuordnung Groß-/Kleinschreibungssensitiv ist und dass Steuerzeichen in Escape-Sequenzen umgewandelt werden, und kombinieren Sie die Funktion mit stripcslashes(), wenn Sie das Escaping rückgängig machen möchten.

Übungen