PHP addcslashes() Function

What You’ll Learn

The addcslashes() function adds backslashes before specific characters you choose. It is ideal when you need fine-grained control over which symbols get escaped—for example, only single quotes in a message, or every lowercase letter in a custom filter.

Definition and Usage

In PHP, addcslashes() is a built-in string function that returns a copy of the input string with a backslash inserted before every character that appears in the $charlist argument. For example, escaping single quotes in "Hello, 'World'!" produces Hello, \'World\'!.

📝 Syntax

The addcslashes() function accepts two string parameters:

string addcslashes(string $str, string $charlist)

Parameters

• $str — the input string to process.
• $charlist — characters to escape. Can include individual characters, hyphen ranges (e.g. a-z), or octal ranges (e.g. \0..\37 for ASCII control characters).

Return Value

Returns a new string with backslashes added before the specified characters. The original $str is not modified.

Examples Gallery

Run these examples in any PHP 7+ environment. Each one demonstrates a common pattern beginners encounter with addcslashes().

<?php
$original = "Hello, 'World'!";
$escaped  = addcslashes($original, "'");

echo "Original: $original\n";
echo "Escaped:  $escaped\n";
?>

Original: Hello, 'World'!
Escaped:  Hello, \'World\'!

<?php
$path = 'C:\Users\name\Documents';
$safe = addcslashes($path, "\\'");

echo $safe . "\n";
?>

C:\\Users\\name\\Documents

<?php
$text = "PHP 8 is fun!";
$result = addcslashes($text, "a-z");

echo $result . "\n";
?>

PHP 8 \i\s \f\u\n!

<?php
$userInput = "price.is $9.99 (USD)";
$escaped   = addcslashes($userInput, ".$()*\\");

$pattern = "/^" . $escaped . "$/";
echo "Pattern: $pattern\n";
echo preg_match($pattern, $userInput) ? "Match!\n" : "No match\n";
?>

Pattern: /^price\.is \$9\.99 \(USD\)$/
Match!

<?php
$text = 'She said "Hi" and it\'s fine\\';

echo "addcslashes (quotes only):\n";
echo addcslashes($text, "'\"") . "\n\n";

echo "addslashes (default set):\n";
echo addslashes($text) . "\n";
?>

addcslashes (quotes only):
She said \"Hi\" and it\'s fine\

addslashes (default set):
She said \"Hi\" and it\\\'s fine\\

🚀 Common Use Cases

• Custom string filters — escape only the characters your parser treats as special.
• Building dynamic regex — prefix backslashes before metacharacters (though preg_quote() is preferred).
• Legacy code maintenance — read older PHP that uses charlist-based escaping.
• Data serialization — prepare strings for formats that require selective escaping.
• Learning string handling — understand how PHP inserts escape characters before moving to higher-level tools like prepared statements.

📝 Notes

• Hyphen ranges in charlist expand to every character in the range—be careful with unintended matches (e.g. a-z includes every lowercase letter).
• If charlist starts with .., the next two characters define an inclusive range (PHP-specific syntax).
• Use stripcslashes() to reverse escaping with the same charlist.
• Do not rely on addcslashes() for SQL safety—use prepared statements instead.
• For HTML output, prefer htmlspecialchars() or htmlentities().

💡 Best Practices