Fonction string PHP addcslashes()

La fonction addcslashes() retourne une chaîne avec un antislash (\) ajouté avant chaque caractère que vous listez dans une « liste de caractères ». Son nom vient de l'échappement en style C : contrairement à addslashes(), qui n'échappe que les quatre caractères fixes ', ", \ et NUL, addcslashes() vous laisse décider quels caractères seront échappés.

Cette page couvre la syntaxe, la façon d'échapper des caractères individuels et des plages entières, les pièges à éviter, et quand utiliser addcslashes() plutôt qu'une alternative plus sûre.

Syntaxe

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

La fonction prend deux paramètres, tous deux obligatoires :

• $string — la chaîne d'entrée à traiter.
• $characters — la liste des caractères à échapper. Vous pouvez lister les caractères individuellement ("W3d") ou sous forme de plage avec .. ("a..z").

Valeur de retour

Elle retourne une nouvelle chaîne avec un antislash inséré avant chaque caractère présent dans $characters. La chaîne originale n'est pas modifiée, car les chaînes en PHP sont passées par valeur.

Notez que certains caractères sont échappés en style C plutôt qu'avec un antislash littéral : les caractères dont le code ASCII est inférieur ou égal à 32, ou supérieur ou égal à 127, sont convertis en leur séquence d'échappement C (par exemple un saut de ligne devient \n, une tabulation devient \t, et d'autres caractères de contrôle deviennent octaux comme \037).

Échapper des caractères individuels

L'utilisation la plus simple consiste à lister exactement les caractères que vous souhaitez échapper.

Exemple 1

Résultat :

Hello\, World!

Seule la virgule était dans la liste de caractères, donc seule la virgule reçoit un antislash devant elle.

Exemple 2

Vous pouvez lister plusieurs caractères à la fois. Chaque occurrence de n'importe quel caractère listé est échappée, et la correspondance est sensible à la casse — échapper "W" n'affecte pas le "w" minuscule.

Résultat :

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

Les deux caractères "W", le "3" et le "d" ont chacun été précédés d'un antislash. Les lettres minuscules n'ont pas été modifiées.

Échapper une plage de caractères

Pour échapper une suite de caractères consécutifs, donnez un début et une fin séparés par ... Par exemple, "A..Z" échappe toutes les lettres majuscules et "0..9" échappe tous les chiffres :

<?php

$string = "Price: 25 USD";

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

echo $escaped_string;

?>

Résultat :

Price: \2\5 USD

La plage doit être croissante. Écrire "z..a" (décroissant) ne produit pas la plage de a à z ; PHP émet un avertissement et traite les points littéralement. Mettez toujours le point de code le plus bas en premier.

Pièges courants

• Échapper \0, \r, \n, \t est dangereux. Ces caractères ont une signification particulière dans les séquences d'échappement C. Si vous les passez dans $characters, vous pouvez finir par convertir des caractères d'une façon non souhaitée ; évitez-les à moins de savoir exactement ce que vous voulez.
• La correspondance est sensible à la casse. Incluez les deux casses (par exemple "Ww" ou la plage "A..z") si vous avez besoin de capturer les deux.
• La chaîne originale est inchangée. addcslashes() retourne une nouvelle chaîne ; pensez à assigner ou à utiliser sa valeur de retour.

Quand l'utiliser

Utilisez addcslashes() lorsque vous devez échapper un ensemble personnalisé de caractères — par exemple pour construire une chaîne destinée à un système qui traite certains caractères de façon particulière. Pour la tâche courante d'échapper les guillemets et les antislashs dans le cadre d'une gestion de chaînes héritée, utilisez plutôt addslashes(). Pour échapper des caractères dans des expressions régulières, utilisez quotemeta(), et pour rendre une entrée utilisateur sûre en sortie HTML, utilisez htmlspecialchars().

Pour inverser l'échappement appliqué par addcslashes(), utilisez stripcslashes().

Important : addcslashes() n'est pas une fonctionnalité de sécurité. Ne comptez jamais sur elle pour prévenir les injections SQL ou assainir du HTML — utilisez des requêtes préparées et htmlspecialchars() pour ces tâches.

Conclusion

La fonction addcslashes() échappe un ensemble personnalisé de caractères dans une chaîne en utilisant les règles du style C, vous offrant un contrôle plus précis qu'addslashes(). Listez les caractères individuellement ou sous forme de plage .. croissante, gardez à l'esprit que la correspondance est sensible à la casse et que les caractères de contrôle sont convertis en séquences d'échappement, et associez-la à stripcslashes() lorsque vous avez besoin d'annuler l'échappement.

Pratique