iconv_substr — Funktion · PHP-Referenz

Signatur

iconv_substr(string $string, int $offset, int|null $length = null, string $encoding = iconv_get_encoding('internal_encoding')): string|false

Beschreibung

iconv_substr() extrahiert einen Teilstring aus $string, indem sie Zeichenpositionen statt Byte-Positionen verwendet. Dies ist besonders wichtig bei Multibyte-Zeichenkodierungen wie UTF-8, EUC-JP oder GB2312, bei denen ein einzelnes Zeichen mehrere Bytes belegen kann und substr() zu fehlerhaften Ergebnissen führen würde.

Der Parameter $offset gibt die Startposition in Zeichen an. Negative Werte werden vom Ende des Strings aus gezählt. Der optionale Parameter $length legt die maximale Anzahl der zurückzugebenden Zeichen fest – auch hier sind negative Werte erlaubt und bedeuten, dass entsprechend viele Zeichen vom Ende ausgelassen werden.

Wird kein $encoding angegeben, verwendet die Funktion die intern gesetzte iconv-Kodierung, die mit iconv_get_encoding('internal_encoding') abgefragt werden kann. Es empfiehlt sich, die Kodierung stets explizit zu übergeben, um unerwartetes Verhalten zu vermeiden.

Die Funktion ist der PHP-eigenen mb_substr() sehr ähnlich, gehört jedoch zur iconv-Erweiterung. In modernen Projekten wird häufig mb_substr() bevorzugt, da die mbstring-Erweiterung breiter verfügbar ist und mehr Zeichensatz-Optionen bietet.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Der Eingabe-String, aus dem ein Teilstring extrahiert werden soll.
$offset Pflicht	int		Startposition in Zeichen (nicht Bytes). Bei negativen Werten wird vom Ende des Strings aus gezählt.
$length	int\|null	null	Maximale Anzahl der zurückzugebenden Zeichen. Negative Werte lassen entsprechend viele Zeichen am Ende aus. Wird `null` übergeben, wird bis zum Ende des Strings extrahiert.
$encoding	string	iconv_get_encoding('internal_encoding')	Die Zeichenkodierung des Strings, z. B. `"UTF-8"`, `"EUC-JP"` oder `"ISO-8859-1"`. Sollte stets explizit gesetzt werden.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den extrahierten Teilstring zurück. Im Fehlerfall – etwa bei ungültiger Kodierung oder ungültigem $offset – wird false zurückgegeben.

Beispiele

Teilstring aus einem UTF-8-String extrahieren

<?php
$text = 'Héllo Wörld';

// Bytes 0-4 wären mit substr() falsch — iconv_substr zählt Zeichen
$teil = iconv_substr($text, 0, 5, 'UTF-8');
echo $teil; // Héllo

$rest = iconv_substr($text, 6, null, 'UTF-8');
echo $rest; // Wörld

Héllo Wörld

Japanische Zeichen korrekt zuschneiden

<?php
// Japanischer String in UTF-8
$japanisch = 'こんにちは世界';

// Erstes Wort (5 Zeichen: こんにちは)
$gruss = iconv_substr($japanisch, 0, 5, 'UTF-8');
echo $gruss . PHP_EOL; // こんにちは

// Letzten 2 Zeichen (negativer Offset)
$ende = iconv_substr($japanisch, -2, null, 'UTF-8');
echo $ende . PHP_EOL; // 世界

こんにちは世界

Negativer length-Parameter

<?php
$text = 'Programmierung';

// Alle Zeichen außer den letzten 4
$teil = iconv_substr($text, 0, -4, 'UTF-8');
echo $teil; // Programmi

Programmi

// Wichtig · Fallstricke

Unterschied zu substr(): Die eingebaute Funktion substr() arbeitet byte-basiert. Bei Multibyte-Encodings wie UTF-8 kann sie Multibyte-Zeichen mitten in der Byte-Sequenz trennen und so ungültige Strings erzeugen. iconv_substr() ist hier die sichere Alternative.

Vergleich mit mb_substr(): Beide Funktionen leisten ähnliches. mb_substr() aus der mbstring-Erweiterung ist in der Praxis jedoch weiter verbreitet und wird in modernen PHP-Projekten häufiger empfohlen. Beide Erweiterungen müssen separat aktiviert sein.

Rückgabe false: Wenn $offset außerhalb der Stringlänge liegt, gibt die Funktion in manchen PHP-Versionen einen leeren String zurück, in anderen false. Daher sollte das Ergebnis mit === false auf Fehler geprüft werden.

Siehe auch

iconv_strlen iconv_strpos mb_substr substr iconv_get_encoding