PHP string функция addcslashes()

Функция addcslashes() возвращает строку с обратным слешем (\), добавленным перед каждым символом из указанного «списка символов». Название происходит от экранирования в стиле C: в отличие от addslashes(), которая всегда экранирует только четыре фиксированных символа — ', ", \ и NUL, — функция addcslashes() позволяет самостоятельно выбирать, какие символы экранировать.

На этой странице рассматриваются синтаксис, способы экранирования отдельных символов и целых диапазонов, возможные подводные камни, а также ситуации, когда следует использовать addcslashes(), а когда лучше обратиться к более безопасной альтернативе.

Синтаксис

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

Функция принимает два обязательных параметра:

• $string — входная строка для обработки.
• $characters — список символов для экранирования. Символы можно перечислять по одному ("W3d") или задавать диапазон через .. ("a..z").

Возвращаемое значение

Функция возвращает новую строку, перед каждым символом которой, входящим в $characters, добавлен обратный слеш. Исходная строка не изменяется, поскольку в PHP строки передаются по значению.

Обратите внимание: некоторые символы экранируются в стиле C, а не буквальным обратным слешем: символы с кодами ASCII 32 и ниже или 127 и выше преобразуются в соответствующие C-последовательности экранирования (например, символ новой строки становится \n, табуляция — \t, а другие управляющие символы — восьмеричными, вроде \037).

Экранирование отдельных символов

Простейший вариант — перечислить именно те символы, которые нужно экранировать.

Пример 1

Вывод:

Hello\, World!

В списке символов была только запятая, поэтому обратный слеш добавлен только перед ней.

Пример 2

Можно перечислить сразу несколько символов. Каждое вхождение любого из них будет экранировано, при этом сопоставление чувствительно к регистру — экранирование "W" не затрагивает строчную "w".

Вывод:

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

Перед обоими символами "W", символом "3" и символом "d" добавлен обратный слеш. Строчные буквы остались без изменений.

Экранирование диапазона символов

Чтобы экранировать непрерывный ряд символов, укажите начало и конец диапазона, разделив их ... Например, "A..Z" экранирует все заглавные буквы, а "0..9" — все цифры:

<?php

$string = "Price: 25 USD";

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

echo $escaped_string;

?>

Вывод:

Price: \2\5 USD

Диапазон должен быть возрастающим. Запись "z..a" (убывающий порядок) не создаёт диапазон от a до z: PHP выдаёт предупреждение и воспринимает точки буквально. Всегда ставьте символ с меньшим кодом на первое место.

Частые ошибки

• Экранирование \0, \r, \n, \t опасно. Эти символы имеют специальное значение в C-последовательностях экранирования. Если передать их в $characters, можно получить неожиданные преобразования символов, поэтому избегайте этого, если точно не знаете, что делаете.
• Сопоставление чувствительно к регистру. Включайте оба регистра (например, "Ww" или диапазон "A..z"), если нужно учитывать и заглавные, и строчные буквы.
• Исходная строка не изменяется. addcslashes() возвращает новую строку; не забывайте присваивать или использовать возвращаемое значение.

Когда применять

Используйте addcslashes(), когда необходимо экранировать произвольный набор символов — например, при формировании строки для системы, которая особым образом трактует определённые символы. Для типичной задачи экранирования кавычек и обратных слешей при работе с устаревшим кодом используйте addslashes(). Для экранирования символов в регулярных выражениях применяйте quotemeta(), а для безопасного вывода пользовательских данных в HTML — htmlspecialchars().

Чтобы отменить экранирование, применённое функцией addcslashes(), используйте stripcslashes().

Важно: addcslashes() не является средством обеспечения безопасности. Никогда не полагайтесь на неё для защиты от SQL-инъекций или санитизации HTML — для этого используйте подготовленные запросы и htmlspecialchars().

Заключение

Функция addcslashes() экранирует произвольный набор символов в строке по правилам стиля C, предоставляя более гибкий контроль, чем addslashes(). Перечисляйте символы по одному или задавайте возрастающий диапазон через .., помните о чувствительности к регистру и о том, что управляющие символы преобразуются в последовательности экранирования, а для отмены экранирования используйте stripcslashes().

Практика