iconv_strpos — Funktion · PHP-Referenz

Signatur

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

Beschreibung

iconv_strpos() sucht innerhalb des Strings $haystack nach dem ersten Auftreten von $needle und gibt die Position als Zeichenposition (nicht Byte-Position) zurück. Im Unterschied zu strpos() arbeitet diese Funktion zeichenkodierungsbewusst, was bei Multibyte-Zeichensätzen wie UTF-8, EUC-JP oder Shift-JIS entscheidend ist, da ein Zeichen dort mehrere Bytes umfassen kann.

Über den Parameter $offset kann die Suche ab einer bestimmten Zeichenposition gestartet werden. Dies ist nützlich, wenn man mehrfache Vorkommen einer Zeichenfolge iterativ suchen möchte. Der Offset ist ebenfalls in Zeichen, nicht in Bytes angegeben.

Der optionale Parameter $encoding gibt die zu verwendende Zeichenkodierung an. Wird er weggelassen oder auf null gesetzt, wird die interne iconv-Kodierung verwendet, die mit iconv_get_encoding('internal_encoding') abgefragt werden kann. In modernen Anwendungen empfiehlt sich alternativ mb_strpos(), das flexibler und breiter unterstützt wird.

Die Funktion eignet sich besonders für Anwendungen, die gezielt mit iconv-kompatiblen Kodierungen arbeiten oder bei denen eine präzise Zeichenpositionsberechnung in Nicht-ASCII-Texten erforderlich ist, etwa beim Verarbeiten von japanischen, chinesischen oder arabischen Texten.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der zu durchsuchende String (Heuhaufen), in dem nach der Nadel gesucht wird.
$needle Pflicht	string		Der gesuchte Teilstring (Nadel). Muss ein nicht-leerer String sein.
$offset	int	0	Die Zeichenposition (nicht Byte-Position), ab der die Suche beginnen soll. Muss nicht-negativ sein.
$encoding	?string	null	Die zu verwendende Zeichenkodierung, z. B. `"UTF-8"` oder `"EUC-JP"`. Wird `null` übergeben oder der Parameter weggelassen, wird die interne iconv-Kodierung genutzt.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Zeichenposition des ersten Vorkommens von $needle in $haystack zurück (beginnend bei 0). Gibt false zurück, wenn die Nadel nicht gefunden wurde. Achtung: Da 0 eine gültige Position ist, muss der Rückgabewert mit === auf false geprüft werden.

Beispiele

Einfache UTF-8-Suche

<?php
$text = 'Héllo Wörld, héllo PHP!';
$pos = iconv_strpos($text, 'héllo', 0, 'UTF-8');

if ($pos !== false) {
    echo "Gefunden an Zeichenposition: " . $pos;
} else {
    echo "Nicht gefunden.";
}
// Beachte: Zeichenposition != Byte-Position bei Multibyte-Zeichen

Gefunden an Zeichenposition: 13

Alle Vorkommen einer Nadel iterativ finden

<?php
$haystack = 'Das ist ein Test. Ein Test ist es.';
$needle   = 'Test';
$encoding = 'UTF-8';
$offset   = 0;

echo "Vorkommen von '" . $needle . "':\n";
while (($pos = iconv_strpos($haystack, $needle, $offset, $encoding)) !== false) {
    echo "  Position: " . $pos . "\n";
    $offset = $pos + iconv_strlen($needle, $encoding);
}

Vorkommen von 'Test': Position: 12 Position: 22

Suche in japanischem Text (EUC-JP)

<?php
// Beispiel mit EUC-JP kodiertem Text
$haystack = iconv('UTF-8', 'EUC-JP', 'こんにちは世界');
$needle   = iconv('UTF-8', 'EUC-JP', '世界');

$pos = iconv_strpos($haystack, $needle, 0, 'EUC-JP');

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

Nadel an Zeichenposition: 5

// Wichtig · Fallstricke

Strikte Vergleiche verwenden: Da Position 0 (erstes Zeichen) ein gültiges Ergebnis ist, darf der Rückgabewert niemals mit == auf false geprüft werden. Immer === false verwenden, um Fehlalarme bei einem Fund an Position 0 zu vermeiden.

Leere Nadel: Eine leere Zeichenfolge als $needle führt zu einer E_WARNING und gibt false zurück.

Alternative: In den meisten modernen Projekten wird mb_strpos() bevorzugt, da die mbstring-Erweiterung eine breitere Kodierungsunterstützung bietet und aktiver gepflegt wird. iconv_strpos() ist sinnvoll, wenn bereits intensiv mit der iconv-Erweiterung gearbeitet wird.

Negativer Offset: Im Gegensatz zu mb_strpos() unterstützt iconv_strpos() keine negativen Offset-Werte; ein negativer Offset führt zu einer Warnung.

Siehe auch

iconv_strrpos iconv_strlen iconv_substr mb_strpos strpos