addcslashes
Adds backslashes before a chosen set of characters, using C-style escape sequences.
addcslashes(string $string, string $characters): string- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The string to be escaped. |
$characters | string | The characters to escape. Ranges may be given as "a..z". Characters below ASCII 32 or above 126 are written as C escapes or octal. |
Return value
stringThe escaped string.
addcslashes() escapes exactly the characters you name, in the style the C language uses. Characters you list that are also C escape sequences become \n, \r, \t, \v, \f, \a, \b or \0; other listed characters below ASCII 32 or above 126 become three-digit octal escapes such as \177; everything else listed simply gets a backslash in front of it.
When to reach for it
Reach for it when you are generating source code or a wire format that another parser will read back: a C or JavaScript string literal, a config file value, a log line that must stay on one line, or a debug dump of binary data where control bytes need to be visible. The character list can be a range, so "\0..\37" escapes every control character in one go.
What trips people up
Ranges are ASCII ranges. If the first character has a higher code than the second, no range is built at all — only the two endpoints and the literal dots are escaped, silently. And escaping the letters 0, a, b, f, n, r, t or v turns them into the corresponding control-character escape, which is almost never what you meant.
Example
When to use it
- Emitting a PHP array as a valid C or JavaScript string literal in a code generator.
- Making control characters visible when dumping binary data to a log.
- Keeping a multi-line value on a single line in a flat config or log format.
Frequently asked questions
What is the difference between addcslashes and addslashes?
addslashes() escapes a fixed set — single quote, double quote, backslash and NUL — for quoting into a string. addcslashes() escapes whichever characters you name, using C escape sequences and octal for non-printables.
Is addcslashes safe for escaping SQL values?
No. Use prepared statements with bound parameters, or a driver-specific escape function. addcslashes() knows nothing about SQL quoting rules and will not protect you from injection.
Why did escaping the letter n turn it into a newline?
Because \n is a C escape sequence, and addcslashes() emits real escape sequences. Listing 0, a, b, f, n, r, t or v in the characters argument produces the corresponding control character rather than a backslash followed by the letter.
More examples
Ranges, and the range that is not one
The first line is unchanged because the input has no uppercase letters. The second escapes each of F, O and O. The third shows the trap: 'z' has a higher ASCII code than 'A', so no range is built and only the literal characters z, . and A are escaped — output is \zoo['\.']. Always order ranges low to high.
<?php
echo addcslashes('foo[bar]', 'A..Z'), "\n";
echo addcslashes('FOO[bar]', 'A..Z'), "\n";
echo addcslashes("zoo['.']", 'z..A'), "\n";Making binary data printable
The character list covers control bytes (0-31), the backslash, and everything from 127 up. The NUL becomes the C escape \0 and byte 0x7F becomes octal \177, so the six raw bytes print as ten visible characters with no invisible or terminal-breaking output. This is the safe way to log arbitrary binary payloads.
<?php
$binary = "AB\x00CD\x7f";
$safe = addcslashes($binary, "\0..\37\\\177..\377");
echo $safe, "\n";
var_dump(strlen($binary), strlen($safe));Beware the letter escapes
Escaping the letter 'a' does not produce \a as two characters — it produces the real BEL control character (0x07), because \a is a C escape sequence. The same happens for 0, b, f, n, r, t and v. The var_dump confirms the bytes are control characters, not backslash-letter pairs, which is why these letters should be kept out of the character list.
<?php
$name = 'banana tart';
echo addcslashes($name, 'a'), "\n";
var_dump(addcslashes($name, 'a') === "b\anan\a t\art");
echo addcslashes($name, 'n'), "\n";
Discussion