Función de string PHP addcslashes()

La función addcslashes() devuelve un string con una barra invertida (\) añadida antes de cada carácter que incluyas en una "lista de caracteres". El nombre proviene del escape al estilo C: a diferencia de addslashes(), que siempre escapa únicamente los cuatro caracteres fijos ', ", \ y NUL, addcslashes() te permite elegir qué caracteres se escapan.

Esta página cubre la sintaxis, cómo escapar tanto caracteres individuales como rangos completos, los errores comunes a tener en cuenta y cuándo usar addcslashes() frente a una alternativa más segura.

Sintaxis

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

La función recibe dos parámetros, ambos obligatorios:

• $string — el string de entrada que se va a procesar.
• $characters — la lista de caracteres a escapar. Puedes listar los caracteres individualmente ("W3d") o como un rango con .. ("a..z").

Valor de retorno

Devuelve un nuevo string con una barra invertida insertada antes de cada carácter que aparezca en $characters. El string original no se modifica, ya que los strings en PHP se pasan por valor.

Ten en cuenta que algunos caracteres se escapan al estilo C en lugar de con una barra invertida literal: los caracteres con códigos ASCII de 32 o menos, o de 127 o más, se convierten a su secuencia de escape C (por ejemplo, un salto de línea se convierte en \n, una tabulación en \t, y otros caracteres de control en octal como \037).

Escapar caracteres individuales

El uso más sencillo consiste en listar los caracteres exactos que deseas escapar.

Ejemplo 1

Salida:

Hello\, World!

Solo la coma estaba en la lista de caracteres, por lo que solo la coma recibe una barra invertida delante.

Ejemplo 2

Puedes listar varios caracteres a la vez. Cada aparición de cualquier carácter listado se escapa, y la coincidencia es sensible a mayúsculas y minúsculas — escapar "W" no afecta a una "w" en minúscula.

Salida:

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

Ambos caracteres "W", el "3" y la "d" recibieron una barra invertida como prefijo. Las letras en minúscula no se modificaron.

Escapar un rango de caracteres

Para escapar una secuencia contigua de caracteres, indica un inicio y un fin separados por ... Por ejemplo, "A..Z" escapa todas las letras mayúsculas y "0..9" escapa todos los dígitos:

<?php

$string = "Price: 25 USD";

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

echo $escaped_string;

?>

Salida:

Price: \2\5 USD

El rango debe ser creciente. Escribir "z..a" (descendente) no produce el rango de a a z; PHP emite una advertencia y trata los puntos como literales. Coloca siempre el punto de código más bajo en primer lugar.

Errores comunes

• Escapar \0, \r, \n, \t es peligroso. Estos caracteres tienen un significado especial en las secuencias de escape de C. Si los incluyes en $characters, puedes terminar convirtiendo caracteres de formas no deseadas, así que evítalos a menos que sepas exactamente lo que quieres.
• La coincidencia distingue entre mayúsculas y minúsculas. Incluye ambos casos (por ejemplo "Ww" o el rango "A..z") si necesitas capturar los dos.
• El string original no cambia. addcslashes() devuelve un nuevo string; recuerda asignar o usar su valor de retorno.

Cuándo usarla

Recurre a addcslashes() cuando necesites escapar un conjunto personalizado de caracteres — por ejemplo, al construir un string para un sistema que trata ciertos caracteres de forma especial. Para la tarea habitual de escapar comillas y barras invertidas en el manejo heredado de strings, usa addslashes(). Para escapar caracteres en expresiones regulares, usa quotemeta(), y para que la entrada del usuario sea segura en la salida HTML, usa htmlspecialchars().

Para revertir el escape que aplica addcslashes(), usa stripcslashes().

Importante: addcslashes() no es una función de seguridad. Nunca confíes en ella para prevenir inyección SQL ni para sanear HTML — usa sentencias preparadas y htmlspecialchars() para esas tareas.

Conclusión

La función addcslashes() escapa un conjunto personalizado de caracteres en un string usando las reglas de estilo C, lo que te da un control más preciso que addslashes(). Lista los caracteres individualmente o como un rango .. creciente, recuerda que la coincidencia distingue entre mayúsculas y minúsculas y que los caracteres de control se convierten en secuencias de escape, y combínala con stripcslashes() cuando necesites deshacer el escape.

Práctica