Funzione string PHP addcslashes()

La funzione addcslashes() restituisce una string con un backslash (\) aggiunto prima di ogni carattere elencato in una "lista di caratteri". Il nome deriva dall'escape in stile C: a differenza di addslashes(), che esegue l'escape solo dei quattro caratteri fissi ', ", \ e NUL, addcslashes() ti permette di decidere tu quali caratteri vengono sottoposti all'escape.

Questa pagina tratta la sintassi, come eseguire l'escape sia di singoli caratteri che di interi intervalli, le insidie da tenere a mente e quando scegliere addcslashes() rispetto a un'alternativa più sicura.

Sintassi

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

La funzione accetta due parametri, entrambi obbligatori:

• $string — la string di input da elaborare.
• $characters — l'elenco dei caratteri da sottoporre all'escape. Puoi elencare i caratteri singolarmente ("W3d") oppure come intervallo con .. ("a..z").

Valore restituito

Restituisce una nuova string con un backslash inserito prima di ogni carattere presente in $characters. La string originale non viene modificata, poiché le string in PHP vengono passate per valore.

Nota che alcuni caratteri vengono sottoposti all'escape in stile C anziché con un backslash letterale: i caratteri con codice ASCII pari o inferiore a 32, o pari o superiore a 127, vengono convertiti nella loro sequenza di escape C (ad esempio un a capo diventa \n, un tab diventa \t e altri caratteri di controllo diventano ottali come \037).

Escape di singoli caratteri

L'utilizzo più semplice consiste nell'elencare esattamente i caratteri che vuoi sottoporre all'escape.

Esempio 1

Output:

Hello\, World!

Solo la virgola era nella lista dei caratteri, quindi solo la virgola riceve un backslash davanti.

Esempio 2

Puoi elencare più caratteri contemporaneamente. Ogni occorrenza di qualsiasi carattere elencato viene sottoposta all'escape, e la corrispondenza è case-sensitive — eseguire l'escape di "W" non ha effetto sulla "w" minuscola.

Output:

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

Entrambi i caratteri "W", il "3" e la "d" sono stati preceduti da un backslash. Le lettere minuscole sono rimaste invariate.

Escape di un intervallo di caratteri

Per eseguire l'escape di una sequenza contigua di caratteri, specifica un inizio e una fine separati da ... Ad esempio, "A..Z" esegue l'escape di ogni lettera maiuscola e "0..9" esegue l'escape di ogni cifra:

<?php

$string = "Price: 25 USD";

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

echo $escaped_string;

?>

Output:

Price: \2\5 USD

L'intervallo deve essere crescente. Scrivere "z..a" (decrescente) non produce l'intervallo da a a z; PHP emette un avviso e tratta i punti letteralmente. Inserisci sempre prima il code point inferiore.

Insidie comuni

• Eseguire l'escape di \0, \r, \n, \t è pericoloso. Questi hanno un significato speciale nelle sequenze di escape C. Se li passi in $characters potresti finire per convertire caratteri in modi non previsti, quindi evitali a meno che tu non sappia esattamente cosa stai facendo.
• La corrispondenza è case-sensitive. Includi entrambi i casi (ad esempio "Ww" o l'intervallo "A..z") se devi intercettare entrambi.
• La string originale rimane invariata. addcslashes() restituisce una nuova string; ricorda di assegnare o di utilizzare il valore restituito.

Quando usarla

Usa addcslashes() quando hai bisogno di eseguire l'escape di un insieme personalizzato di caratteri — ad esempio per costruire una string destinata a un sistema che tratta certi caratteri in modo speciale. Per il compito comune di eseguire l'escape di virgolette e backslash nella gestione legacy delle string, usa invece addslashes(). Per eseguire l'escape di caratteri destinati alle espressioni regolari, usa quotemeta(), e per rendere sicuro l'input dell'utente per l'output HTML, usa htmlspecialchars().

Per annullare l'escape applicato da addcslashes(), usa stripcslashes().

Importante: addcslashes() non è una funzionalità di sicurezza. Non fare mai affidamento su di essa per prevenire l'SQL injection o per sanificare l'HTML — usa istruzioni preparate e htmlspecialchars() per questi scopi.

Conclusione

La funzione addcslashes() esegue l'escape di un insieme personalizzato di caratteri in una string utilizzando le regole in stile C, offrendoti un controllo più preciso rispetto a addslashes(). Elenca i caratteri singolarmente o come intervallo crescente con .., ricorda che la corrispondenza è case-sensitive e che i caratteri di controllo vengono convertiti in sequenze di escape, e abbinala a stripcslashes() quando hai bisogno di annullare l'escape.

Pratica