mb_stristr — Funktion · PHP-Referenz

Signatur

mb_stristr(string $haystack, string $needle, bool $before_needle = false, ?string $encoding = null): string|false

Beschreibung

mb_stristr() ist die Multibyte-sichere, Groß-/Kleinschreibung ignorierende Variante von mb_strstr(). Sie durchsucht den String haystack nach dem ersten Vorkommen von needle und gibt standardmäßig den Teil ab dem Treffer bis zum Stringende zurück. Das ist besonders wichtig bei Sprachen wie Deutsch, Türkisch oder Griechisch, wo Umlaute und besondere Zeichen mehrere Bytes belegen und einfaches stristr() falsche Ergebnisse liefert.

Durch den Parameter before_needle kann gesteuert werden, ob der Teil vor dem Treffer zurückgegeben werden soll. So lassen sich Strings bequem in zwei Hälften aufteilen, ohne den Fundort manuell berechnen zu müssen.

Der optionale Parameter encoding legt die Zeichenkodierung fest (z. B. 'UTF-8'). Wird er weggelassen, verwendet die Funktion die interne Kodierung, die mit mb_internal_encoding() gesetzt wurde.

Die Funktion gibt false zurück, wenn needle nicht gefunden wird. Um dies korrekt zu prüfen, sollte stets mit === verglichen werden, da ein leerer Rückgabestring ebenfalls falsy wäre.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der zu durchsuchende Eingabe-String (Heuhaufen).
$needle Pflicht	string		Der gesuchte Teilstring (Nadel). Die Groß-/Kleinschreibung wird ignoriert.
$before_needle	bool	false	Wenn `true`, wird der Teil von `haystack` vor dem ersten Treffer zurückgegeben. Standardmäßig (`false`) wird der Teil ab dem Treffer (inklusive) zurückgegeben.
$encoding	?string	null	Die zu verwendende Zeichenkodierung, z. B. `'UTF-8'`. Bei `null` wird die interne Kodierung (`mb_internal_encoding()`) verwendet.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den Teilstring ab dem ersten Treffer bis zum Stringende zurück (oder den Teil davor, wenn before_needle = true). Wird needle nicht gefunden, wird false zurückgegeben.

Beispiele

Einfache Suche ohne Beachtung der Groß-/Kleinschreibung

<?php
$text = 'Willkommen auf programmierung.net – Viel Spaß!';
$suche = 'PROGRAMMIERUNG';

$ergebnis = mb_stristr($text, $suche, false, 'UTF-8');

if ($ergebnis !== false) {
    echo $ergebnis;
} else {
    echo 'Nicht gefunden.';
}

programmierung.net – Viel Spaß!

Teil vor dem Treffer ermitteln (before_needle = true)

<?php
$text = 'Benutzer: Hans Müller <hans@example.com>';
$suche = '<HANS';

$vorher = mb_stristr($text, $suche, true, 'UTF-8');
$nachher = mb_stristr($text, $suche, false, 'UTF-8');

if ($vorher !== false) {
    echo 'Vor dem Treffer: ' . $vorher . PHP_EOL;
    echo 'Ab dem Treffer: ' . $nachher . PHP_EOL;
}

Vor dem Treffer: Benutzer: Hans Müller Ab dem Treffer: <hans@example.com>

Umlaute und Multibyte-Zeichen korrekt behandeln

<?php
$text = 'Die Ärzte spielen heute Abend.';
$suche = 'ärzte';

$ergebnis = mb_stristr($text, $suche, false, 'UTF-8');

if ($ergebnis !== false) {
    echo 'Gefunden: ' . $ergebnis;
} else {
    echo 'Nicht gefunden – möglicherweise falsches Encoding.';
}

Ärzte spielen heute Abend.

// Wichtig · Fallstricke

Rückgabe prüfen mit ===: Da ein leerer String in PHP als falsy gilt, sollte der Rückgabewert immer mit === false auf Nichtfunden geprüft werden, nicht mit != false oder einer einfachen if-Negation.

Encoding-Fallstrick: Wird kein encoding angegeben und die interne Kodierung wurde nicht korrekt auf UTF-8 gesetzt, kann es bei Umlauten und Sonderzeichen zu unerwarteten Ergebnissen kommen. Es empfiehlt sich, die Kodierung stets explizit zu übergeben.

Unterschied zu stristr(): Die eingebaute Funktion stristr() ist nicht Multibyte-sicher und kann bei Strings mit Multibyte-Zeichen (z. B. UTF-8) falsche oder keine Ergebnisse liefern. Für solche Strings sollte ausschließlich mb_stristr() verwendet werden.

Siehe auch

mb_strstr mb_stripos mb_strpos stristr mb_internal_encoding