Signatur
Beschreibung
grapheme_substr() funktioniert ähnlich wie substr(), arbeitet jedoch nicht auf Byte- oder Zeichenebene, sondern auf Basis von Graphem-Clustern. Ein Graphem-Cluster ist die kleinste wahrnehmbare Einheit in einem Schriftsystem – zum Beispiel ein Buchstabe mit kombiniertem Akzent oder Emoji mit Hautfarbmodifikator werden als ein Graphem gezählt, obwohl sie intern mehrere Code-Punkte oder Bytes belegen.
Dies ist besonders wichtig bei der Verarbeitung von Texten in Sprachen mit kombinierten Zeichen (z. B. Devanagari, Thai, Arabisch) oder bei modernen Emoji-Strings, bei denen substr() oder mb_substr() fehlerhafte oder unvollständige Zeichensequenzen produzieren könnten.
Der Parameter offset gibt die Startposition in Graphem-Clustern an; negative Werte zählen vom Ende des Strings. Der optionale Parameter length begrenzt die Anzahl der zurückgegebenen Graphem-Cluster; auch hier sind negative Werte erlaubt und bewirken, dass entsprechend viele Grapheme vom Ende weggelassen werden.
Die Funktion ist Teil der Intl-Erweiterung (International Components for Unicode) und muss daher zusammen mit dieser Erweiterung verfügbar sein. Sie ist die korrekte Wahl überall dort, wo vollständige Unicode-Korrektheit bei Teilstring-Operationen erforderlich ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Der Eingabe-String in UTF-8-Kodierung, aus dem der Teilstring extrahiert werden soll. | |
| $offset Pflicht | int | Startposition in Graphem-Clustern. Ein positiver Wert zählt vom Anfang des Strings, ein negativer Wert vom Ende. Liegt der Offset außerhalb der Stringlänge, gibt die Funktion false zurück. |
|
| $length | ?int | null | Maximale Anzahl der zurückzugebenden Graphem-Cluster. Wird null übergeben oder weggelassen, werden alle Grapheme ab offset bis zum Stringende zurückgegeben. Ein negativer Wert bewirkt, dass die entsprechende Anzahl Grapheme vom Ende des Strings weggelassen wird. |
Rückgabewert
false zurück, wenn offset außerhalb der Stringlänge liegt oder ein Fehler aufgetreten ist.Beispiele
Einfaches Extrahieren eines Graphem-Teilstrings
<?php
// Ein String mit einem kombinierten Zeichen: 'e' + Combining Acute Accent (U+0301)
$string = "Cafe\u{0301} au lait";
// mb_strlen() sieht 'e' und den Akzent als getrennte Code-Punkte
echo mb_strlen($string) . "\n"; // 16
// grapheme_strlen() zählt sie als ein Graphem-Cluster
echo grapheme_strlen($string) . "\n"; // 15
// Ersten 5 Graphem-Cluster extrahieren
$result = grapheme_substr($string, 0, 5);
echo $result . "\n"; // Café (mit korrekt kombiniertem é)Negativer Offset und negativer Length-Parameter
<?php
// Emoji-String: jedes Emoji ist ein Graphem-Cluster
$string = "Hello 👨👩👧👦🌍🎉";
// Alle Grapheme ab Position 6 (die Emojis)
$emojis = grapheme_substr($string, 6);
echo $emojis . "\n"; // 👨👩👧👦🌍🎉
// Letztes Graphem
$last = grapheme_substr($string, -1);
echo $last . "\n"; // 🎉
// Alles außer den letzten 2 Graphemen
$withoutLast2 = grapheme_substr($string, 0, -2);
echo $withoutLast2 . "\n"; // Hello 👨👩👧👦// Wichtig · Fallstricke
Voraussetzung: Die intl-Erweiterung muss in der PHP-Installation aktiviert sein. Ohne sie steht grapheme_substr() nicht zur Verfügung. Überprüfen Sie die Verfügbarkeit mit extension_loaded('intl').
Kodierung: Der Eingabe-String muss gültig UTF-8-kodiert sein. Bei ungültigen UTF-8-Sequenzen ist das Verhalten undefiniert. Validieren Sie Eingaben ggf. vorher mit mb_check_encoding($string, 'UTF-8').
Unterschied zu mb_substr(): mb_substr() zählt Unicode-Code-Punkte, nicht Graphem-Cluster. Bei zusammengesetzten Zeichen (Basiszeichen + Combining Character) oder mehrteiligen Emoji-Sequenzen kann mb_substr() den String an einer ungültigen Stelle trennen, während grapheme_substr() immer an Graphem-Grenzen schneidet.