grapheme_strstr — Funktion · PHP-Referenz

Signatur

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

Beschreibung

grapheme_strstr() durchsucht den Eingabe-String $haystack nach dem ersten Vorkommen von $needle und gibt den Rest des Strings ab dieser Position zurück. Die Funktion arbeitet auf Basis von Unicode-Graphem-Clustern (intl-Erweiterung), sodass mehrbyte-kodierte Zeichen und kombinierte Zeichen (z. B. Buchstaben mit Diakritika) korrekt behandelt werden.

Im Gegensatz zu strstr() oder mb_strstr() orientiert sich grapheme_strstr() nicht an Bytes oder Code-Points, sondern an sichtbaren Zeichen im Sinne des Unicode-Standards. Dies ist besonders wichtig für Sprachen wie Devanagari, Arabisch oder Thai, bei denen ein sichtbares Zeichen aus mehreren Code-Points zusammengesetzt sein kann.

Mit dem Parameter $before_needle lässt sich steuern, ob der Teil vor dem ersten Vorkommen der Nadel zurückgegeben werden soll. Dies entspricht dem Verhalten von strstr() mit gleichnamigem Parameter.

Die Funktion ist Teil der intl-Erweiterung (International Components for Unicode) und muss daher in der PHP-Installation verfügbar sein.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der zu durchsuchende Eingabe-String in UTF-8-Kodierung.
$needle Pflicht	string		Der gesuchte Teilstring (Nadel) in UTF-8-Kodierung. Darf kein leerer String sein.
$before_needle	bool	false	Wenn `true`, wird der Teil des Strings vor dem ersten Vorkommen der Nadel zurückgegeben; standardmäßig (`false`) der Teil ab dem ersten Vorkommen (einschließlich der Nadel).

Rückgabewert

Typ

string|false

Beschreibung

Gibt den gesuchten Teilstring als string zurück. Falls $needle nicht in $haystack gefunden wird, wird false zurückgegeben.

Beispiele

Grundlegende Verwendung: Teil ab dem Vorkommen der Nadel

<?php
$text = 'Héllo Wörld, Héllo PHP!';
$result = grapheme_strstr($text, 'Wörld');
echo $result; // Wörld, Héllo PHP!

Wörld, Héllo PHP!

Teil vor dem ersten Vorkommen der Nadel

<?php
$text = 'Héllo Wörld, Héllo PHP!';
$result = grapheme_strstr($text, 'Wörld', true);
echo $result; // Héllo

Héllo

Umgang mit kombinierten Unicode-Zeichen (Graphem-Cluster)

<?php
// 'ä' kann als einzelnes Zeichen (U+00E4) oder als 'a' + Combining Umlaut (U+0061 U+0308) vorliegen
$haystack = "Stra\u{00DF}e und Br\u{00FC}cke";
$needle   = "Br\u{00FC}cke";
$result = grapheme_strstr($haystack, $needle);
echo $result; // Brücke

Brücke

Nadel nicht gefunden

<?php
$text = 'Héllo Wörld';
$result = grapheme_strstr($text, 'PHP');
if ($result === false) {
    echo 'Nadel nicht gefunden.';
}

Nadel nicht gefunden.

// Wichtig · Fallstricke

Voraussetzung: Die intl-Erweiterung muss in PHP aktiviert sein (extension=intl in der php.ini). Ohne diese Erweiterung ist die Funktion nicht verfügbar.

Leere Nadel: Eine leere Zeichenkette als $needle führt zu einem Fehler bzw. gibt false zurück – dies sollte im Code immer vorab geprüft werden.

Unterschied zu mb_strstr(): mb_strstr() arbeitet auf Basis von Multibyte-Code-Points, nicht auf Graphem-Cluster-Ebene. Für korrekte Unicode-Verarbeitung bei kombinierten Zeichen sollte bevorzugt grapheme_strstr() verwendet werden.

Groß-/Kleinschreibung: Die Funktion ist case-sensitive. Für eine Suche ohne Berücksichtigung der Groß-/Kleinschreibung steht grapheme_stristr() zur Verfügung.

Siehe auch

grapheme_stristr grapheme_strpos grapheme_substr mb_strstr strstr