grapheme_stripos — Funktion · PHP-Referenz

Signatur

grapheme_stripos(string $haystack, string $needle, int $offset = 0): int|false

Beschreibung

grapheme_stripos() durchsucht den String $haystack nach dem ersten Vorkommen von $needle, wobei Groß- und Kleinschreibung ignoriert wird. Im Gegensatz zu strpos() oder stripos() arbeitet diese Funktion mit Graphem-Clustern statt mit Bytes oder Zeichen, was bei Unicode-Strings (insbesondere mit kombinierten Zeichen, Akzenten oder Emoji) korrekte Ergebnisse liefert.

Der Rückgabewert ist die Position des Treffers in Graphem-Einheiten, beginnend bei 0. Diese Funktion ist besonders wichtig, wenn man mit mehrsprachigen Texten arbeitet, da viele Unicode-Zeichen aus mehreren Bytes bestehen und stripos() dabei fehlerhafte Positionen zurückgeben würde.

Der optionale Parameter $offset gibt an, ab welcher Graphem-Position die Suche beginnen soll. Ein negativer Offset wird seit PHP 7.1 unterstützt und bezeichnet eine Position vom Ende des Strings aus.

Die Funktion ist Teil der Intl-Extension (Internationalization Functions) und muss mit aktivierter intl-Erweiterung verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der Eingabestring, in dem gesucht werden soll.
$needle Pflicht	string		Der gesuchte Teilstring. Die Suche erfolgt unabhängig von Groß- und Kleinschreibung.
$offset	int	0	Startposition (in Graphem-Einheiten) für die Suche. Negative Werte suchen vom Ende des Strings aus (ab PHP 7.1).

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Position des ersten Treffers als int (in Graphem-Einheiten, 0-basiert) zurück. Wenn $needle nicht gefunden wird, wird false zurückgegeben. Bei der Auswertung unbedingt den strikten Vergleich (=== false) verwenden, da Position 0 sonst fälschlicherweise als false interpretiert werden kann.

Beispiele

Einfache Suche mit Groß-/Kleinschreibung ignorieren

<?php
$text = 'Héllo Wörld';
$pos = grapheme_stripos($text, 'wörld');

if ($pos !== false) {
    echo "Gefunden an Graphem-Position: " . $pos;
} else {
    echo "Nicht gefunden.";
}

Gefunden an Graphem-Position: 6

Suche mit Offset und Vergleich zu stripos

<?php
// Kombinierende Zeichen: 'é' als e + Kombinationszeichen (2 Bytes)
$haystack = 'café Café latté';
$needle   = 'café';

// grapheme_stripos liefert korrekte Graphem-Positionen
$gPos = grapheme_stripos($haystack, $needle, 1);
echo "grapheme_stripos: " . $gPos . PHP_EOL;

// stripos liefert Byte-Positionen, kann bei Multibyte-Zeichen abweichen
$sPos = stripos($haystack, $needle, 1);
echo "stripos:          " . $sPos . PHP_EOL;

grapheme_stripos: 5 stripos: 6

Suche nach Emoji-Cluster (kein Treffer)

<?php
$text   = 'Hello 🌍 World';
$needle = 'planet';

$pos = grapheme_stripos($text, $needle);

var_dump($pos);

bool(false)

// Wichtig · Fallstricke

Achtung beim Vergleich: Da die Funktion bei einem Treffer an Position 0 den Integer 0 zurückgibt, der beim losen Vergleich (==) als false gewertet wird, ist stets der strikte Vergleich === false zu verwenden.

Voraussetzung: Die PHP-Erweiterung intl muss aktiviert sein (extension=intl in der php.ini). Ist sie nicht verfügbar, löst PHP einen fatalen Fehler aus.

Für die einfache Byteposition (ohne Unicode-Unterstützung) steht stripos() zur Verfügung; für Multibyte-Strings ohne Graphem-Cluster-Unterstützung eignet sich mb_stripos(). grapheme_stripos() liefert die präzisesten Ergebnisse für vollständige Unicode-Texte.

Siehe auch

grapheme_strpos grapheme_substr grapheme_strlen mb_stripos stripos