Função de string PHP addcslashes()

A função addcslashes() retorna uma string com uma barra invertida (\) adicionada antes de cada caractere que você listar numa "lista de caracteres". O nome vem do estilo de escaping do C: ao contrário de addslashes(), que escapa apenas os quatro caracteres fixos ', ", \ e NUL, addcslashes() permite que você decida quais caracteres são escapados.

Esta página aborda a sintaxe, como escapar tanto caracteres individuais quanto intervalos inteiros, as armadilhas a serem observadas, e quando usar addcslashes() em vez de uma alternativa mais segura.

Sintaxe

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

A função recebe dois parâmetros, ambos obrigatórios:

• $string — a string de entrada a ser processada.
• $characters — a lista de caracteres a escapar. Você pode listar os caracteres individualmente ("W3d") ou como um intervalo com .. ("a..z").

Valor de Retorno

Retorna uma nova string com uma barra invertida inserida antes de cada caractere que aparece em $characters. A string original não é modificada, pois strings em PHP são passadas por valor.

Observe que alguns caracteres são escapados no estilo C em vez de com uma barra invertida literal: caracteres com códigos ASCII 32 e abaixo, ou 127 e acima, são convertidos para sua sequência de escape C (por exemplo, uma nova linha se torna \n, uma tabulação se torna \t, e outros caracteres de controle se tornam octais como \037).

Escapando caracteres individuais

O uso mais simples é listar os exatos caracteres que você deseja escapar.

Exemplo 1

Saída:

Hello\, World!

Apenas a vírgula estava na lista de caracteres, portanto somente a vírgula recebe uma barra invertida antes dela.

Exemplo 2

Você pode listar vários caracteres de uma vez. Cada ocorrência de qualquer caractere listado é escapada, e a correspondência é sensível a maiúsculas e minúsculas — escapar "W" não afeta um "w" minúsculo.

Saída:

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

Ambos os caracteres "W", o "3" e o "d" receberam cada um uma barra invertida como prefixo. As letras minúsculas não foram alteradas.

Escapando um intervalo de caracteres

Para escapar uma sequência contígua de caracteres, forneça um início e um fim separados por ... Por exemplo, "A..Z" escapa todas as letras maiúsculas e "0..9" escapa todos os dígitos:

<?php

$string = "Price: 25 USD";

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

echo $escaped_string;

?>

Saída:

Price: \2\5 USD

O intervalo deve ser crescente. Escrever "z..a" (decrescente) não produz o intervalo de a a z; o PHP emite um aviso e trata os pontos literalmente. Sempre coloque o code point menor primeiro.

Armadilhas comuns

• Escapar \0, \r, \n, \t é perigoso. Esses caracteres têm significado especial nas sequências de escape C. Se você os passar em $characters, pode acabar convertendo caracteres de formas não intencionais, portanto evite-os a menos que saiba exatamente o que deseja.
• A correspondência é sensível a maiúsculas e minúsculas. Inclua ambos os casos (por exemplo "Ww" ou o intervalo "A..z") se precisar capturar os dois.
• A string original não é alterada. addcslashes() retorna uma nova string; lembre-se de atribuir ou usar seu valor de retorno.

Quando usar

Use addcslashes() quando precisar escapar um conjunto personalizado de caracteres — por exemplo, ao construir uma string para um sistema que trata certos caracteres de forma especial. Para a tarefa comum de escapar aspas e barras invertidas no tratamento legado de strings, use addslashes(). Para escapar caracteres em expressões regulares, use quotemeta(), e para tornar a entrada do usuário segura para saída HTML, use htmlspecialchars().

Para reverter o escaping que addcslashes() aplica, use stripcslashes().

Importante: addcslashes() não é um recurso de segurança. Nunca confie nela para prevenir injeção SQL ou para sanitizar HTML — use declarações preparadas e htmlspecialchars() para essas finalidades.

Conclusão

A função addcslashes() escapa um conjunto personalizado de caracteres em uma string usando as regras do estilo C, oferecendo controle mais fino do que addslashes(). Liste os caracteres individualmente ou como um intervalo crescente com .., lembre-se de que a correspondência é sensível a maiúsculas e minúsculas e que os caracteres de controle são convertidos em sequências de escape, e combine-a com stripcslashes() quando precisar desfazer o escaping.

Prática