locale_compose — Funktion · PHP-Referenz

Signatur

locale_compose(array $subtags): string|false

Beschreibung

locale_compose() ist die prozedurale Version von Locale::composeLocale() und gehört zur Intl-Erweiterung. Die Funktion nimmt ein assoziatives Array mit einzelnen Locale-Bestandteilen (Sprache, Schrift, Region, Varianten, Erweiterungen usw.) und setzt daraus eine standardkonforme Locale-ID gemäß BCP 47 / RFC 4646 zusammen.

Typische Anwendungsfälle sind das programmatische Zusammenbauen einer Locale, wenn die einzelnen Teile (z. B. Sprache und Region) getrennt vorliegen, oder wenn eine Locale nach einer Bearbeitung wieder in ihre kanonische Zeichenkettendarstellung überführt werden soll. Das Gegenstück ist locale_parse(), das eine Locale-ID in ihre Bestandteile zerlegt.

Erlaubte Schlüssel im Array sind: language, script, region, variant0 bis variant14, extlang0 bis extlang2, private0 bis private14 sowie extensions (assoziativ, Schlüssel = einbuchstabige Erweiterungs-Singletones). Die einzelnen Subtags werden in der korrekten BCP-47-Reihenfolge mit Bindestrichen verbunden.

Parameter

Name	Typ	Default	Beschreibung
$subtags Pflicht	array		Assoziatives Array mit den Locale-Subtags. Gültige Schlüssel sind `language`, `script`, `region`, `variant0`–`variant14`, `extlang0`–`extlang2`, `private0`–`private14` und `extensions`. Unbekannte Schlüssel werden ignoriert.

Rückgabewert

Typ

string|false

Beschreibung

Gibt die zusammengesetzte Locale-ID als Zeichenkette zurück (z. B. de_AT oder zh-Hant-TW). Gibt false zurück, wenn das Array leer ist oder kein gültiger language-Subtag vorhanden ist.

Beispiele

Einfache Locale aus Sprache und Region zusammensetzen

<?php
$subtags = [
    'language' => 'de',
    'region'   => 'AT',
];

$locale = locale_compose($subtags);
echo $locale;

de_AT

Vollständige Locale mit Schrift, Region und Erweiterung

<?php
$subtags = [
    'language'   => 'zh',
    'script'     => 'Hant',
    'region'     => 'TW',
    'extensions' => [
        'u' => 'ca-gregory',
    ],
];

$locale = locale_compose($subtags);
echo $locale;

zh_Hant_TW@u=ca-gregory

Hin- und Rückkonvertierung mit locale_parse

<?php
$original = 'de_Latn_DE_1901';

// Zerlegen
$parts = locale_parse($original);
var_dump($parts);

// Wieder zusammensetzen
$rebuilt = locale_compose($parts);
echo $rebuilt;

array(4) { ["language"]=> string(2) "de" ["script"]=> string(4) "Latn" ["region"]=> string(2) "DE" ["variant0"]=> string(4) "1901" } de_Latn_DE_1901

// Wichtig · Fallstricke

Voraussetzung: Die Intl-Erweiterung (ext-intl) muss in PHP aktiviert sein, da locale_compose() nicht Teil der PHP-Kernfunktionen ist.

Die Funktion gibt false zurück, wenn kein language-Schlüssel im Array angegeben wurde. Das Ergebnis entspricht nicht zwingend einer durch ICU normalisierten Locale – für eine kanonische Form kann anschließend Locale::canonicalize() aufgerufen werden.

Groß-/Kleinschreibung der Subtag-Werte wird so übernommen, wie sie im Array angegeben wurde. BCP 47 empfiehlt Kleinschreibung für Sprache und Großschreibung (Initial-Großbuchstabe) für Schriftsysteme, aber die Funktion erzwingt dies nicht.

Siehe auch

locale_parse locale_get_default Locale::canonicalize locale_lookup locale_filter_matches