Guida Completa alla Funzione mysqli_set_charset in PHP

Quando si memorizzano nomi, commenti o emoji in MySQL, i byte vengono trasmessi correttamente solo se PHP e il database concordano su un set di caratteri — la mappatura tra byte e caratteri. La funzione mysqli_set_charset imposta il set di caratteri per la connessione tra lo script PHP e il server MySQL, in modo che tutto ciò che si invia e si riceve venga interpretato nello stesso modo su entrambi i lati.

Questa pagina spiega cosa fa la funzione, perché impostare il charset sulla connessione è importante (e perché è anche una misura di sicurezza), e come utilizzarla sia con l'API mysqli procedurale che con quella orientata agli oggetti.

Cosa fa mysqli_set_charset

mysqli_set_charset indica al server MySQL quale set di caratteri utilizzerà il client (lo script PHP) per il resto della connessione. Influisce su come vengono interpretate le stringhe di query, su come vengono codificati i risultati in fase di restituzione e su quali byte mysqli_real_escape_string() tratta come speciali.

La firma procedurale accetta prima la connessione e poi il nome del charset, e restituisce true in caso di successo o false in caso di errore:

mysqli_set_charset(mysqli $connection, string $charset): bool

La forma orientata agli oggetti è un metodo sull'oggetto di connessione:

$connection->set_charset($charset);

L'argomento $charset è un nome di set di caratteri MySQL come utf8mb4, utf8 o latin1 — non un nome di codifica PHP. Usa utf8mb4 per il supporto Unicode completo, inclusi i caratteri a 4 byte come le emoji; il vecchio alias utf8 in MySQL memorizza solo fino a 3 byte per carattere e non può contenere emoji.

Impostalo sulla connessione, non solo nelle query. Eseguire SET NAMES utf8mb4 come query cambia il charset lato server ma non aggiorna il valore che la libreria client C usa per l'escaping. mysqli_set_charset aggiorna entrambi, ed è per questo che è il modo corretto e sicuro per cambiare charset.

Connessione e impostazione del charset

mysqli_set_charset richiede una connessione esistente, quindi prima aprine una con mysqli_connect. L'esempio seguente si connette e poi imposta immediatamente utf8mb4:

<?php

$host     = 'localhost';
$user     = 'username';
$password = 'password';
$database = 'mydatabase';

$connection = mysqli_connect($host, $user, $password, $database);

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

if (!mysqli_set_charset($connection, 'utf8mb4')) {
    die('Error setting charset: ' . mysqli_error($connection));
}

echo 'Current charset: ' . mysqli_character_set_name($connection);
// Current charset: utf8mb4

Dopo che la chiamata ha esito positivo, mysqli_character_set_name riporta il charset attivo, confermando che la modifica è avvenuta.

Esempio orientato agli oggetti

Se utilizzi l'API mysqli orientata agli oggetti, chiama set_charset() come metodo. È buona pratica farlo subito dopo aver costruito la connessione, prima di eseguire qualsiasi query:

<?php

$mysqli = new mysqli('localhost', 'username', 'password', 'mydatabase');

if ($mysqli->connect_errno) {
    die('Connection failed: ' . $mysqli->connect_error);
}

if (!$mysqli->set_charset('utf8mb4')) {
    die('Error setting charset: ' . $mysqli->error);
}

echo $mysqli->character_set_name();
// utf8mb4

Gestione degli errori

mysqli_set_charset restituisce false se il server non supporta il charset richiesto (ad esempio, un errore di battitura come utf8mb44). Controlla sempre il valore restituito invece di presumere il successo:

<?php

if (!mysqli_set_charset($connection, 'utf8mb4')) {
    // Log it and stop — running queries with the wrong charset
    // can corrupt stored text and weaken escaping.
    throw new RuntimeException(
        'Failed to set charset: ' . mysqli_error($connection)
    );
}

Puoi chiamare la funzione più di una volta sulla stessa connessione per cambiare charset a metà sessione, anche se in pratica la si imposta una volta subito dopo la connessione e la si lascia invariata.

Perché è importante

• Testo corretto. Senza un charset corrispondente, le lettere accentate e gli script non latini vengono restituiti come ? o mojibake (caratteri illeggibili come é invece di é).
• Emoji e Unicode completo. Solo utf8mb4 memorizza caratteri a 4 byte; utf8 le elimina o le tronca silenziosamente.
• Sicurezza. mysqli_real_escape_string() esegue l'escape in base al charset della connessione. Impostarlo correttamente chiude una classe di vettori di SQL injection che sfruttano le mancate corrispondenze multibyte. Ciononostante, preferisci le prepared statement all'escaping manuale.

Funzioni correlate

• mysqli_connect — apre la connessione da passare a set_charset.
• mysqli_get_charset — ottieni un oggetto completo che descrive il charset corrente (collation, commento, numero).
• mysqli_character_set_name — ottieni solo il nome del charset attivo.
• mysqli_select_db — cambia il database attivo su una connessione esistente.

Conclusione

mysqli_set_charset allinea il set di caratteri dello script PHP con la connessione MySQL, garantendo che il testo venga trasmesso correttamente e che l'escaping si comporti in modo sicuro. Impostalo su utf8mb4 subito dopo la connessione, controlla il valore restituito e avrai coperto i casi più comuni — dai nomi accentati alle emoji.

Esercitazione