Signatur
Beschreibung
setlocale() ändert die aktuelle Locale-Einstellung des PHP-Prozesses für eine oder mehrere Kategorien. Die Locale beeinflusst das Verhalten von Funktionen wie strftime(), strcoll(), money_format(), number_format() und regulären Ausdrücken mit locale-sensitiven Zeichenklassen.
Die Kategorie wird über eine der vordefinierten Konstanten angegeben (z. B. LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME, LC_MESSAGES). LC_ALL setzt alle Kategorien gleichzeitig.
Es können mehrere Locale-Bezeichner als weitere Argumente übergeben werden – PHP versucht sie der Reihe nach, bis einer erfolgreich gesetzt werden konnte. Alternativ akzeptiert der zweite Parameter ein Array mit mehreren Locale-Namen. Dies ist praktisch, wenn Systeme unterschiedliche Schreibweisen für dieselbe Locale verwenden.
Achtung: Die Locale-Einstellung ist prozessweit und nicht thread-sicher. Wird PHP als Modul unter einem Multi-Thread-Webserver (z. B. Apache mit Worker-MPM) betrieben, kann setlocale() das Verhalten anderer gleichzeitiger Anfragen beeinflussen. In solchen Umgebungen sollte die Locale möglichst früh gesetzt und wieder zurückgestellt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $category Pflicht | int|string | Eine der Locale-Kategorien-Konstanten: LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME oder LC_MESSAGES. Bestimmt, welche Aspekte der Locale geändert werden. |
|
| $locales Pflicht | string|array | Ein Locale-Name (z. B. 'de_DE.UTF-8') oder ein Array mit mehreren Locale-Namen, die der Reihe nach ausprobiert werden. Wird ein leerer String übergeben, wird die Locale aus den Umgebungsvariablen des Systems gelesen. |
|
| $rest | string | Weitere Locale-Namen als einzelne Argumente (Alternative zur Array-Schreibweise). PHP probiert sie der Reihe nach, bis eine Locale erfolgreich gesetzt wurde. |
Rückgabewert
false, wenn keine der angegebenen Locales gesetzt werden konnte (z. B. weil sie auf dem System nicht installiert ist). Wird null oder '' als Locale übergeben, gibt die Funktion die aktuelle Locale zurück, ohne sie zu ändern.Beispiele
Locale für Deutschland setzen und Datum formatieren
<?php
// Locale für Zeit auf Deutsch setzen (verschiedene Schreibweisen versuchen)
$locale = setlocale(LC_TIME, 'de_DE.UTF-8', 'de_DE', 'de', 'german');
if ($locale === false) {
echo 'Locale konnte nicht gesetzt werden.';
} else {
echo 'Aktive Locale: ' . $locale . PHP_EOL;
// Datum auf Deutsch ausgeben (strftime ist in PHP 8.1 deprecated)
echo strftime('%A, %d. %B %Y', mktime(0, 0, 0, 12, 24, 2024));
}Aktuelle Locale abfragen ohne sie zu ändern
<?php
// Aktuelle LC_ALL-Locale auslesen (kein Setzen)
$current = setlocale(LC_ALL, null);
echo 'Aktuelle Locale: ' . $current . PHP_EOL;
// Locale temporär ändern und danach wiederherstellen
$old = setlocale(LC_NUMERIC, '0'); // '0' liest aus, ohne zu setzen
setlocale(LC_NUMERIC, 'de_DE.UTF-8');
echo number_format(1234567.89, 2, ',', '.') . PHP_EOL;
// Alte Locale wiederherstellen
setlocale(LC_NUMERIC, $old);Fallback-Liste mit Array übergeben
<?php
// Verschiedene Locale-Namen als Array – plattformunabhängiger Code
$result = setlocale(LC_MONETARY, [
'fr_FR.UTF-8',
'fr_FR',
'French_France.1252',
'french'
]);
if ($result !== false) {
echo 'Gesetzte Locale: ' . $result . PHP_EOL;
// money_format ist deprecated ab PHP 7.4; Beispiel zur Illustration
$info = localeconv();
echo 'Währungssymbol: ' . $info['currency_symbol'] . PHP_EOL;
} else {
echo 'Keine passende Locale gefunden.' . PHP_EOL;
}// Wichtig · Fallstricke
Thread-Sicherheit: setlocale() setzt die Locale prozess- bzw. threadweit. Unter Multi-Thread-Webservern (z. B. Apache mit Worker- oder Event-MPM) kann das die Ausgabe anderer gleichzeitiger Anfragen beeinflussen. CLI-Skripte oder PHP-FPM sind davon weniger betroffen.
Verfügbarkeit der Locale: Die Funktion schlägt fehl (false), wenn die gewünschte Locale auf dem Betriebssystem nicht installiert ist. Unter Debian/Ubuntu lassen sich Locales mit locale-gen de_DE.UTF-8 und dpkg-reconfigure locales installieren.
Deprecated-Hinweis: strftime() und money_format(), die stark von setlocale() abhängen, sind seit PHP 8.1 bzw. 7.4 deprecated. Als moderne Alternative empfiehlt sich die IntlDateFormatter- und NumberFormatter-Klasse aus der intl-Extension, die keine systemweite Locale-Änderung benötigen.
Um die aktuell gesetzte Locale auszulesen ohne sie zu verändern, übergibt man als zweiten Parameter null, 0 oder einen leeren String – das Verhalten kann je nach PHP-Version und Plattform leicht abweichen; null ist am portabelsten.