mb_strpos — Funktion · PHP-Referenz

Signatur

mb_strpos(string $haystack, string $needle, int $offset = 0, ?string $encoding = null): int|false

Beschreibung

mb_strpos() ist die multibyte-sichere Variante von strpos(). Sie sucht in einem Zeichenketten-Ausdruck (haystack) nach dem ersten Auftreten eines Suchstrings (needle) und gibt dessen Zeichenposition (0-basiert) zurück. Im Gegensatz zu strpos() werden dabei Multibyte-Zeichenkodierungen (z. B. UTF-8, UTF-16) korrekt berücksichtigt, sodass Zeichen wie Umlaute oder CJK-Zeichen nicht in Einzelbytes zerlegt werden und zu falschen Positionen führen.

Der optionale Parameter $offset erlaubt es, die Suche an einer bestimmten Zeichenposition zu beginnen. Ein positiver Wert überspringt die ersten n Zeichen, ein negativer Wert (ab PHP 7.1) beginnt n Zeichen vom Ende des Strings. Die Funktion ist Groß-/Kleinschreibungs-sensitiv; für eine schreibungsunabhängige Suche steht mb_stripos() zur Verfügung.

Gibt die Funktion false zurück, bedeutet das, dass needle nicht gefunden wurde. Da 0 (Position am Anfang) und false bei laxem Vergleich (==) identisch sind, muss der Rückgabewert stets mit dem strikten Vergleichsoperator === geprüft werden.

Die zu verwendende Zeichenkodierung kann explizit über $encoding angegeben werden; wird sie weggelassen, greift die intern gesetzte Kodierung (via mb_internal_encoding()), die standardmäßig UTF-8 ist.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Die Zeichenkette, in der gesucht wird.
$needle Pflicht	string		Der gesuchte Teilstring. Ab PHP 8.0 muss dies ein String sein; ältere Versionen akzeptierten auch einen Integer (Ordinalwert), was jedoch als veraltet gilt.
$offset	int	0	Startposition der Suche als Zeichenindex (0-basiert). Negative Werte sind ab PHP 7.1 erlaubt und zählen vom Ende des Strings.
$encoding	?string	null	Name der Zeichenkodierung, z. B. `'UTF-8'` oder `'ISO-8859-1'`. Wird `null` übergeben, gilt die interne Kodierung (`mb_internal_encoding()`).

Rückgabewert

Typ

int|false

Beschreibung

Die 0-basierte Zeichenposition des ersten Vorkommens von needle in haystack, oder false, wenn needle nicht gefunden wurde. Immer mit === vergleichen, da Position 0 sonst fälschlich als false interpretiert werden kann.

Beispiele

Einfache Suche in einem UTF-8-String

<?php
$text = 'Fußball ist großartig';
$pos  = mb_strpos($text, 'groß', 0, 'UTF-8');

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

Gefunden an Position: 14

Prüfung auf Nicht-Fund mit striktem Vergleich

<?php
$text = 'Über den Wolken';

// Korrekte Prüfung mit ===
if (mb_strpos($text, 'Über') === false) {
    echo "Nicht gefunden.";
} else {
    echo "Gefunden an Position: " . mb_strpos($text, 'Über');
}

Gefunden an Position: 0

Suche mit positivem Offset überspringt Zeichen

<?php
$text = 'Käse, Käse und mehr Käse';

// Erstes Vorkommen
$erstePos = mb_strpos($text, 'Käse');
echo "Erstes Vorkommen: " . $erstePos . "\n";

// Zweites Vorkommen durch Offset nach dem ersten
$zweitePos = mb_strpos($text, 'Käse', $erstePos + 1);
echo "Zweites Vorkommen: " . $zweitePos;

Erstes Vorkommen: 0 Zweites Vorkommen: 6

// Wichtig · Fallstricke

Achtung: Verwechseln Sie nicht Byte-Offset (wie bei strpos()) und Zeichen-Offset (wie bei mb_strpos()). Bei UTF-8-Strings, die Multibyte-Zeichen enthalten, liefern beide Funktionen unterschiedliche Ergebnisse.

Der Rückgabewert false und der Positionswert 0 sind bei lockerem Vergleich (==) identisch. Nutzen Sie immer === false, um zu prüfen, ob der String nicht gefunden wurde.

Falls kein $encoding-Parameter angegeben und keine interne Kodierung gesetzt wurde, greift PHP auf den internen Standard zurück. Es empfiehlt sich, die Kodierung explizit zu übergeben oder einmalig mit mb_internal_encoding('UTF-8') zu setzen.

Siehe auch

strpos mb_stripos mb_strrpos mb_substr mb_internal_encoding mb_strstr