character_set_name

La funzione mysqli_character_set_name() restituisce il set di caratteri predefinito in uso per la connessione MySQLi corrente — ad esempio utf8mb4, utf8 o latin1. Questa pagina spiega cosa restituisce la funzione, la sua sintassi in entrambi gli stili, quando utilizzarla e i problemi di codifica che aiuta a individuare.

Cosa controlla il set di caratteri

Il set di caratteri della connessione indica a MySQL come interpretare i byte inviati (nelle istruzioni INSERT/UPDATE e nei parametri delle query) e come codificare i byte restituiti. Se il charset della connessione non corrisponde alla codifica effettiva delle stringhe, si ottiene il mojibake — lettere accentate corrotte, emoji trasformate in ???? e perdita silenziosa di dati.

mysqli_character_set_name() è il modo più rapido per ispezionare tale impostazione in fase di esecuzione. È una diagnostica di sola lettura: non modifica nulla. Per modificare il charset si usa set_charset().

Sintassi

La funzione dispone di una forma orientata agli oggetti e di una forma procedurale. Sono equivalenti — scegli quella che corrisponde al tuo codebase.

// Object-oriented style
string $mysqli->character_set_name()

// Procedural style
string mysqli_character_set_name(mysqli $mysqli)

• Parametro (solo procedurale): $mysqli — una connessione restituita da mysqli_connect() o new mysqli().
• Valore restituito: una string contenente il nome del set di caratteri corrente (es. "utf8mb4"). Non restituisce false; su una connessione valida è sempre presente un charset.

Come usare mysqli_character_set_name()

Chiamala su una connessione aperta e stampa il risultato:

<?php
$mysqli = new mysqli("localhost", "your_username", "your_password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

echo "Character set: " . $mysqli->character_set_name();

$mysqli->close();
?>

Un output tipico, prima di impostare qualcosa esplicitamente, è quello predefinito del server:

Character set: utf8mb4

La stessa cosa in stile procedurale:

<?php
$mysqli = mysqli_connect("localhost", "your_username", "your_password", "database");
if (mysqli_connect_errno()) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Character set: " . mysqli_character_set_name($mysqli);

mysqli_close($mysqli);
?>

Leggere il charset dopo averlo modificato

Poiché la funzione riporta l'impostazione attiva, è utile per confermare che una chiamata a set_charset() abbia avuto effetto:

<?php
$mysqli = new mysqli("localhost", "your_username", "your_password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

echo "Before: " . $mysqli->character_set_name() . "\n";

$mysqli->set_charset("utf8mb4");
echo "After:  " . $mysqli->character_set_name() . "\n";

$mysqli->close();
?>

Before: latin1
After:  utf8mb4

Perché impostare il charset invece di leggerlo soltanto

mysqli_character_set_name() si limita a riportare il charset — non può correggerlo. Per il supporto completo a Unicode (inclusi emoji e molti caratteri CJK) imposta utf8mb4 subito dopo la connessione:

<?php
$mysqli = new mysqli("localhost", "your_username", "your_password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

$mysqli->set_charset("utf8mb4");
$mysqli->query("INSERT INTO users (name, email) VALUES ('Jörg 🚀', '[email protected]')");

$mysqli->close();
?>

Note e problemi comuni:

• Preferisci utf8mb4 a utf8. Il utf8 storico di MySQL è un alias a 3 byte che non può memorizzare caratteri a 4 byte come gli emoji. utf8mb4 è il vero UTF-8 completo.
• Non eseguire SET NAMES ... come query per cambiare il charset. Aggiorna la sessione lato server ma lascia la libreria client all'oscuro, il che compromette real_escape_string(). Usa sempre set_charset() in modo che entrambi restino sincronizzati.
• Il nome restituito è il charset della connessione, indipendente dal charset di una colonna o tabella definito nello schema.

Funzioni correlate

• mysqli_set_charset() — cambia il set di caratteri della connessione.
• mysqli_get_charset() — restituisce un object completo che descrive il charset (collation, lunghezza in byte e altro).
• mysqli_connect_errno() / mysqli_connect_error() — rileva gli errori di connessione prima di leggere il charset.
• PHP MySQLi overview — l'estensione MySQLi nel suo insieme.

Conclusione

mysqli_character_set_name() è uno strumento diagnostico semplice e affidabile per verificare quale set di caratteri sta utilizzando una connessione MySQL. Usala per eseguire il debug di problemi di codifica, quindi risolvili con set_charset("utf8mb4") in modo che l'applicazione memorizzi correttamente testi accentati ed emoji.

Pratica