grapheme_strpos — Funktion · PHP-Referenz

Signatur

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

Beschreibung

grapheme_strpos() arbeitet ähnlich wie strpos(), zählt jedoch nicht Bytes oder Zeichen, sondern Graphem-Cluster – also sichtbare Zeichen im Unicode-Sinne. Ein Graphem-Cluster kann aus mehreren Code-Points bestehen (z. B. ein Basiszeichen + Combining-Accent), wird aber als eine einzige sichtbare Einheit wahrgenommen. Die Funktion ist daher korrekt für mehrsprachige Texte, insbesondere bei Sprachen mit diakritischen Zeichen, Emoji-Sequenzen oder komplexen Schriftsystemen.

Die Suche ist Groß-/Kleinschreibung-sensitiv. Für eine Suche ohne Berücksichtigung der Groß-/Kleinschreibung steht grapheme_stripos() zur Verfügung. Der zurückgegebene Offset ist ein Graphem-Offset, kein Byte- oder Code-Point-Offset, was ihn z. B. für den Einsatz in grapheme_substr() direkt nutzbar macht.

Intern nutzt die Funktion die ICU-Bibliothek (Internationalization Components for Unicode), die über die Intl-Extension in PHP eingebunden wird. Sie ist Teil der intl-Extension und steht nur zur Verfügung, wenn diese kompiliert bzw. geladen ist.

Wichtig: Der Parameter $offset erlaubt, die Suche an einer bestimmten Graphem-Position zu beginnen; negative Offsets werden ab PHP 7.1+ unterstützt und zählen vom Ende des Strings.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der Eingabe-String, in dem gesucht wird. Muss ein gültiger UTF-8-String sein.
$needle Pflicht	string		Der zu suchende Teilstring. Muss ein gültiger UTF-8-String sein. Leerer String führt zu einem Rückgabewert von `false`.
$offset	int	0	Optionale Start-Position der Suche in Graphem-Einheiten. Ein positiver Wert beginnt vom Anfang, ein negativer Wert (ab PHP 7.1) zählt vom Ende des Strings.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Position des ersten Vorkommens von $needle in $haystack als Graphem-Offset (nullbasiert) zurück. Wird $needle nicht gefunden, wird false zurückgegeben. Der Rückgabewert 0 bedeutet, dass $needle am Anfang des Strings gefunden wurde – daher beim Vergleich immer === statt == verwenden.

Beispiele

Einfache Graphem-Positionssuche mit diakritischen Zeichen

<?php
// Der String enthält Zeichen mit Combining-Accents (Graphem-Cluster)
$haystack = "café crème";
$needle   = "crème";

$pos = grapheme_strpos($haystack, $needle);

if ($pos !== false) {
    echo "Gefunden an Graphem-Position: " . $pos . PHP_EOL;
    // Korrekte Extraktion mit grapheme_substr
    echo grapheme_substr($haystack, $pos) . PHP_EOL;
} else {
    echo "Nicht gefunden." . PHP_EOL;
}

Gefunden an Graphem-Position: 5 crème

Vergleich mit strpos() bei Emoji-Sequenzen

<?php
// Emoji-Sequenz: Frau + Hautfarbe = 1 Graphem-Cluster, aber mehrere Bytes/Code-Points
$haystack = "Hallo 👩🏽 Welt";
$needle   = "Welt";

$graphemPos = grapheme_strpos($haystack, $needle);
$bytePos    = strpos($haystack, $needle);

echo "Graphem-Position: " . $graphemPos . PHP_EOL; // Korrekt: 8
echo "Byte-Position:    " . $bytePos    . PHP_EOL; // Falsch für Anzeige/Slice: viel größer

Graphem-Position: 8 Byte-Position: 19

Suche mit negativem Offset (ab PHP 7.1)

<?php
// Suche nur im letzten Teil des Strings
$haystack = "Straße auf der Straße";
$needle   = "Straße";

// Suche ab 5 Grapheme vor dem Ende
$pos = grapheme_strpos($haystack, $needle, -6);

if ($pos !== false) {
    echo "Letztes Vorkommen ab Offset -6 gefunden an Position: " . $pos . PHP_EOL;
} else {
    echo "Nicht gefunden." . PHP_EOL;
}

Letztes Vorkommen ab Offset -6 gefunden an Position: 15

// Wichtig · Fallstricke

Achtung beim Vergleich: Da grapheme_strpos() bei Erfolg auch 0 zurückgeben kann (Treffer am Anfang), muss der Rückgabewert immer mit dem strikten Vergleichsoperator === auf false geprüft werden. Ein Vergleich mit == würde Position 0 fälschlicherweise als false interpretieren.

Voraussetzung: Die Funktion setzt die PHP-Extension intl voraus. Ohne diese Extension existiert grapheme_strpos() nicht und führt zu einem fatalen Fehler. Sicherstellen, dass extension=intl in der php.ini aktiviert ist.

Kodierung: Haystack und Needle müssen gültige UTF-8-Strings sein. Ungültige UTF-8-Sequenzen können zu unerwarteten Ergebnissen oder false führen.

Siehe auch

grapheme_stripos grapheme_strrpos grapheme_substr mb_strpos strpos