addcslashes()

Purpose

addcslashes() returns a copy of a string in which every character you list is preceded by a backslash. Unlike addslashes(), which always targets a fixed set of characters, you decide which characters get quoted. You can also describe a range of characters with the .. notation. Control characters and bytes outside the printable ASCII range are written in a C-like style, so the result is easy to read and can be reversed with stripcslashes().

Signature

Parameters

• $string: the text to escape. PHP treats it as a sequence of bytes.
• $characters: the list of characters to escape. There is no default, so both arguments are required. You can write single characters, such as "lo", or ranges, such as A..Z. A range runs from the first byte value to the second, inclusive.

Return value and failure cases

The function always returns a string. There is no false return and no exception for ordinary string input. If none of the listed characters appear in the input, you get the same text back.

The main way to go wrong is a malformed range. If the first character of a range has a higher ASCII value than the second, no range is built. Only the start character, the end character and the dots are escaped, and PHP also reports a warning for the invalid range. Check byte values with ord() if you are unsure.

How escaping is written

For most printable characters the output is simply a backslash followed by the character. When the characters you list include control bytes or bytes above 126 that are not alphanumeric, PHP writes them differently. Names such as \n, \t and \r are used where C has them. Other such bytes become a three-digit octal sequence, like \001.

Example 1: listed characters and a range

The first call escapes every l and o. The second uses the range A..z, which covers all letters and also the punctuation bytes between Z and a, namely [ \ ] ^ _ and the backtick.

<?php
echo addcslashes("Hello, World!", "lo"), "\n";
echo addcslashes('foo[ ]', 'A..z'), "\n";

He\l\l\o, W\or\ld!
\f\o\o\[ \]

The space is not in the range, so it stays unescaped.

Example 2: control characters

The double-quoted sequence "\0..\37" means the bytes from 0 to 31 in octal notation. That covers tabs, newlines and other non-printing bytes, so they become visible escape sequences.

<?php
$text = "A\tB\x01\n";
echo addcslashes($text, "\0..\37"), "\n";

A\tB\001\n

The tab turns into the two characters \t, byte 1 turns into \001, and the newline turns into \n. The final "\n" in the code is the real newline emitted by the script.

Example 3: quotes and backslashes, with a round trip

Escaping the double quote and the backslash itself is a common use. Because stripcslashes() understands the same notation, you can verify that nothing was lost.

<?php
$original = 'path C:\temp "quoted"';
$escaped = addcslashes($original, '"\\');
echo $escaped, "\n";
echo json_encode(stripcslashes($escaped) === $original), "\n";

path C:\\temp \"quoted\"
true

In the single-quoted argument '"\\', PHP reads the double backslash as one backslash, so the list contains a double quote and a backslash.

Edge cases

• Empty character list: with nothing to escape, the input is returned unchanged.
• Multibyte text: the function works on bytes. If your list covers a high range such as \177..\377, each byte of a UTF-8 character is rewritten as an octal sequence. Do not use that range for text you want to stay readable.
• Letters that have C meanings: the manual warns about listing 0, a, b, f, n, r, t or v. They become \0, \a, \b, \f, \n, \r, \t and \v, which are predefined C escapes. If you feed the output to PHP or another C-derived language, the result may not mean what you intended.
• Wide ranges: A..z also includes characters you may not have meant to escape. Always count what sits between the endpoints.

Common mistakes

1. Reversing a range such as z..A, which does not create a range.
2. Using addcslashes() as protection for SQL, HTML or shell contexts. It is a generic quoting tool, not a security function. Use prepared statements, htmlspecialchars() or proper argument handling instead.
3. Forgetting that the second argument is also a PHP string. Double-quoted strings interpret \n or \37 before the function sees them, while single-quoted strings do not. Know which one you wrote.
4. Expecting the escaped text to be a valid PHP literal. Octal sequences and C names do not always match PHP's rules.
5. Escaping a letter and forgetting that the output then contains a backslash before that letter, which can look like an escape sequence.

Related functions

• stripcslashes() reverses C-style quoting.
• addslashes() quotes single quotes, double quotes, backslashes and NUL.
• stripslashes() removes simple backslash quoting.
• quotemeta() escapes a fixed set of meta characters.
• htmlspecialchars() converts special characters to HTML entities.

Recap

addcslashes() gives you control over which characters receive a backslash. List characters or use start..end ranges in increasing order, remember that it works on bytes, and take care with letters that have C meanings. Use stripcslashes() to undo the result, and choose a context-specific escaping function for security work.