locale_filter_matches — Funktion · PHP-Referenz

Signatur

locale_filter_matches(string $langtag, string $locale, bool $canonicalize = false): bool

Beschreibung

locale_filter_matches() implementiert das sogenannte Basic Filtering gemäß RFC 4647 und prüft, ob ein Sprach-Tag-Filter (Wildcard * erlaubt) auf ein konkretes Locale-Tag passt. Damit lässt sich z. B. prüfen, ob ein Browser-Accept-Language-Eintrag mit einem bestimmten Locale übereinstimmt.

Die Funktion gehört zur intl-Erweiterung und ist die prozedurale Entsprechung zu Locale::filterMatches(). Ein Filter wie de-* passt auf alle deutschen Locale-Tags (de-DE, de-AT usw.), während ein exakter Filter wie de-DE nur auf genau dieses Tag passt.

Wird $canonicalize auf true gesetzt, werden beide Tags vor dem Vergleich in ihre kanonische Form umgewandelt. Das ist empfehlenswert, wenn die Eingaben aus unbekannten oder externen Quellen stammen, um Varianten wie DE_de korrekt zu behandeln.

Typische Anwendungsgebiete sind die Auswertung von Accept-Language-HTTP-Headern oder die Filterung einer Liste von unterstützten Locales nach dem Wunsch-Locale eines Benutzers.

Parameter

Name	Typ	Default	Beschreibung
$langtag Pflicht	string		Das zu prüfende Locale-Tag (z. B. `de-DE`), das mit dem Filter verglichen wird.
$locale Pflicht	string		Der Sprach-Tag-Filter gemäß RFC 4647 (z. B. `de-` oder `de-DE`). Wildcards (``) sind erlaubt.
$canonicalize	bool	false	Gibt an, ob beide Tags vor dem Vergleich in kanonische Form umgewandelt werden sollen. Empfohlen bei Eingaben aus externen Quellen.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Filter $locale auf das Tag $langtag passt, andernfalls false.

Beispiele

Einfacher Filter-Vergleich mit Wildcard

<?php
// Prüfen ob 'de-AT' auf den Filter 'de-*' passt
$langtag = 'de-AT';
$filter  = 'de-*';

if (locale_filter_matches($langtag, $filter)) {
    echo "'{$langtag}' passt auf den Filter '{$filter}'.";
} else {
    echo "'{$langtag}' passt NICHT auf den Filter '{$filter}'.";
}

'de-AT' passt auf den Filter 'de-*'.

Accept-Language-Header auswerten

<?php
// Simulierter Accept-Language-Header des Browsers
$acceptLanguages = ['fr-FR', 'de-CH', 'en-US'];

// Unterstützte Locale-Filter der Anwendung
$supportedFilters = ['de-*', 'en-*'];

foreach ($acceptLanguages as $lang) {
    foreach ($supportedFilters as $filter) {
        if (locale_filter_matches($lang, $filter, true)) {
            echo "'{$lang}' wird unterstützt (Filter: '{$filter}').\n";
        }
    }
}

'de-CH' wird unterstützt (Filter: 'de-*'). 'en-US' wird unterstützt (Filter: 'en-*').

Kanonisierung bei nicht-standardisierten Eingaben

<?php
// Groß-/Kleinschreibung kann variieren – Kanonisierung hilft
$langtag = 'DE_de'; // nicht-kanonische Schreibweise
$filter  = 'de-DE';

var_dump(locale_filter_matches($langtag, $filter, false)); // ohne Kanonisierung
var_dump(locale_filter_matches($langtag, $filter, true));  // mit Kanonisierung

bool(false) bool(true)

// Wichtig · Fallstricke

Reihenfolge der Parameter: Achtung – die Reihenfolge von $langtag (das konkrete Tag) und $locale (der Filter) ist leicht verwirrend und wird gelegentlich vertauscht. Der Filter ist der zweite Parameter.

Erweiterung: Die Funktion setzt die intl-Erweiterung voraus. Ist diese nicht installiert, führt der Aufruf zu einem fatalen Fehler. Die Verfügbarkeit kann mit extension_loaded('intl') geprüft werden.

OOP-Äquivalent: Die objektorientierte Variante lautet Locale::filterMatches($langtag, $locale, $canonicalize) und verhält sich identisch.

Siehe auch

locale_lookup locale_accept_from_http locale_canonicalize Locale