setlocale()

La funzione PHP setlocale() imposta la locale corrente per uno script — l'insieme di regole specifiche di una cultura che determinano come il testo viene ordinato, come i numeri e le valute vengono formattati, e come le date vengono scritte. Una locale è identificata da una stringa come en_US (inglese americano) o de_DE (tedesco), solitamente combinata con una codifica dei caratteri come .utf8.

Si ricorre a setlocale() ogni volta che una singola base di codice deve produrre output che risulti "nativo" in più di un paese: 1,234.56 per un utente americano, ma 1.234,56 per uno tedesco, January contro Januar, e così via.

Sintassi

setlocale(int $category, string $locale, string ...$locales): string|false

Può anche accettare un singolo array di locale invece di un elenco:

setlocale(int $category, array $locale): string|false

Parametri

• $category — quale gruppo di comportamenti dipendenti dalla locale modificare. Passare una delle costanti LC_*:

  Costante	Influenza
  LC_ALL	Ogni categoria contemporaneamente
  LC_COLLATE	Confronto e ordinamento delle stringhe (vedi strcoll())
  LC_CTYPE	Classificazione dei caratteri e conversione maiuscole/minuscole
  LC_MONETARY	Formattazione della valuta (vedi money_format())
  LC_NUMERIC	Separatore decimale per i numeri
  LC_TIME	Formattazione di data e ora (vedi strftime())
  LC_MESSAGES	Formattazione dei messaggi di sistema (non disponibile su Windows)

• $locale — la stringa della locale da applicare, ad es. 'en_US.utf8'. Tre valori speciali sono utili:

  • "" (stringa vuota) — usa la locale dalle variabili d'ambiente del server.
  • "0" — non modificare nulla; restituisce soltanto l'impostazione corrente per quella categoria.
  • null — equivalente a "0".

• ...$locales — alternative opzionali. PHP prova ogni nome nell'ordine e applica il primo effettivamente installato nel sistema operativo.

Restituisce il nome della locale impostata in caso di successo, oppure false se nessuna delle locale richieste è disponibile.

Esempio di base

<?php
$result = setlocale(LC_ALL, 'en_US.utf8');

if ($result !== false) {
    echo "Locale set to: $result";
} else {
    echo "Requested locale is not installed.";
}
?>

setlocale() restituisce la nuova stringa della locale in caso di successo oppure false in caso di fallimento, quindi verificare sempre il valore restituito — una locale mancante fallisce silenziosamente e lascia la formattazione errata anziché generare un errore.

Fornire alternative

I nomi delle locale differiscono tra i sistemi operativi (en_US.utf8 su Linux, English_United States.1252 su Windows). Elencare più nomi consente allo stesso script di funzionare ovunque — PHP utilizza il primo abbinamento installato trovato:

<?php
$locale = setlocale(
    LC_ALL,
    'en_US.UTF-8',                 // Linux / macOS
    'en_US.utf8',
    'English_United States.1252'   // Windows
);

echo $locale ?: 'No English locale available';
?>

Perché la locale è importante: formattazione dei numeri

Dopo aver impostato LC_NUMERIC (o LC_ALL), le funzioni che rispettano la locale producono output specifico della cultura. In questo caso i separatori decimali e delle migliaia seguono le convenzioni tedesche:

<?php
setlocale(LC_ALL, 'de_DE.utf8', 'de_DE', 'German_Germany.1252');

$info = localeconv();
echo $info['decimal_point'];   // ,
echo "\n";
echo $info['thousands_sep'];   // .
?>

localeconv() legge le regole numeriche e monetarie della locale attiva, che è il metodo più sicuro per formattare i numeri manualmente. Si noti che number_format() di PHP non legge la locale — i separatori vengono passati esplicitamente.

Errori comuni

• La locale deve essere installata sul server. setlocale() ha successo solo per le locale che il sistema operativo conosce. Su un sistema Debian/Ubuntu potrebbe essere necessario eseguire locale-gen de_DE.UTF-8 && update-locale.
• È globale al processo, non thread-safe. L'impostazione influenza l'intero processo PHP, quindi evitare di modificarla contemporaneamente in SAPI multi-thread.
• Non modifica echo o printf() per i float. Utilizzare sprintf() con attenzione; il separatore decimale della locale può sorprendere le funzioni che costruiscono SQL o JSON. Reimpostare con setlocale(LC_NUMERIC, 'C') attorno a tale codice.
• money_format() è stato rimosso in PHP 8.0. Per la valuta, preferire la classe NumberFormatter dell'estensione intl.

Esercitazione