grapheme_stristr — Funktion · PHP-Referenz

Signatur

grapheme_stristr(string $haystack, string $needle, bool $before_needle = false): string|false

Beschreibung

grapheme_stristr() durchsucht den String $haystack nach dem ersten Vorkommen von $needle, wobei Groß- und Kleinschreibung ignoriert wird. Die Funktion arbeitet korrekt mit Unicode-Graphem-Clustern, also mit kombinierten Zeichen, Akzenten und anderen mehrteiligen Unicode-Einheiten, die als ein sichtbares Zeichen erscheinen.

Im Gegensatz zu stristr() (Byte-basiert) oder mb_stristr() (codepoint-basiert) behandelt grapheme_stristr() Graphem-Cluster als atomare Einheiten, was besonders bei Sprachen mit komplexer Schrift (z. B. Devanagari, Arabisch, Emoji-Sequenzen) zu semantisch korrekten Ergebnissen führt.

Wird $before_needle auf true gesetzt, gibt die Funktion stattdessen den Teil des Strings vor dem ersten Vorkommen zurück. Wird die Nadel nicht gefunden, ist der Rückgabewert false.

Diese Funktion setzt die intl-Erweiterung voraus und eignet sich immer dann, wenn Unicode-Textverarbeitung korrekt und sprachsensitiv erfolgen soll.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der zu durchsuchende Eingabe-String (Heuhaufen). Muss UTF-8-kodiert sein.
$needle Pflicht	string		Der gesuchte Teilstring (Nadel). Die Suche erfolgt ohne Beachtung von Groß- und Kleinschreibung. Muss UTF-8-kodiert sein.
$before_needle	bool	false	Wenn `true`, wird der Teil des Strings vor dem ersten Vorkommen von `$needle` zurückgegeben. Standard ist `false`, d. h. es wird der Teil ab einschließlich dem Vorkommen zurückgegeben.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den gefundenen Teilstring (inklusive oder exklusive der Nadel je nach $before_needle) als string zurück. Wird die Nadel nicht gefunden, wird false zurückgegeben.

Beispiele

Einfache Suche ohne Beachtung der Groß-/Kleinschreibung

<?php
$text = 'Héllo World, héllo PHP!';
$nadel = 'HÉLLO';

$ergebnis = grapheme_stristr($text, $nadel);
var_dump($ergebnis);
// Gibt alles ab dem ersten Treffer zurück

$vorher = grapheme_stristr($text, $nadel, true);
var_dump($vorher);
// Gibt alles VOR dem ersten Treffer zurück

string(18) "Héllo World, héllo PHP!" string(0) ""

Praxisbeispiel mit Emoji-Sequenzen und Unicode

<?php
// Graphem-Cluster: é als Basiszeichen + Combining Accent
$haystack = "Cafe\u{0301} und Caf\u{00E9} sind gleich";
$needle   = "CAFE\u{0301}";

$treffer = grapheme_stristr($haystack, $needle);
if ($treffer !== false) {
    echo "Gefunden: " . $treffer . PHP_EOL;
} else {
    echo "Nicht gefunden." . PHP_EOL;
}

// before_needle = true: Teil vor dem Treffer
$vor = grapheme_stristr($haystack, $needle, true);
var_dump($vor);

Gefunden: Café und Café sind gleich string(0) ""

Rückgabe false bei nicht gefundener Nadel

<?php
$text = 'Guten Morgen!';
$nadel = 'Abend';

$ergebnis = grapheme_stristr($text, $nadel);
if ($ergebnis === false) {
    echo "Nadel nicht gefunden.";
}

Nadel nicht gefunden.

// Wichtig · Fallstricke

Voraussetzung: Die intl-Erweiterung muss installiert und aktiviert sein. Ohne sie steht grapheme_stristr() nicht zur Verfügung.

Rückgabe und strenger Vergleich: Prüfe den Rückgabewert immer mit === false statt == false, da ein leerer String "" (wenn die Nadel am Anfang steht und $before_needle = true gesetzt ist) ebenfalls als falsy gilt.

Encoding: Alle übergebenen Strings müssen gültig UTF-8-kodiert sein. Ungültige UTF-8-Sequenzen können zu unerwarteten Ergebnissen oder Fehlern führen.

Für reine ASCII-Texte ist stristr() ausreichend und schneller. Für allgemeines Unicode ohne Graphem-Cluster-Anforderungen kann mb_stristr() verwendet werden.

Siehe auch

grapheme_strstr grapheme_stripos grapheme_strpos mb_stristr stristr