grapheme_str_split — Funktion · PHP-Referenz

Signatur

grapheme_str_split(string $string, int $length = 1): array|false

Beschreibung

grapheme_str_split() arbeitet ähnlich wie str_split(), jedoch auf der Ebene von Unicode-Graphem-Clustern statt auf der Byte-Ebene. Ein Graphem-Cluster ist die kleinste wahrnehmbare Einheit eines Schriftsystems – also das, was ein Benutzer als einzelnes Zeichen wahrnimmt. Das kann ein einfacher ASCII-Buchstabe sein, aber auch ein Basiszeichen kombiniert mit einem oder mehreren Combining-Codepoints (z. B. ein Buchstabe mit Akzent oder ein Emoji mit Hautfarbenmodifikator).

Der Parameter length gibt an, wie viele Graphem-Cluster jedes Array-Element enthalten soll. Der Standardwert 1 liefert jedes Graphem als eigenes Element. Ist die Länge größer als 1, werden entsprechend viele Grapheme zusammengefasst. Das letzte Element des Arrays kann kürzer sein, wenn die Gesamtzahl der Grapheme kein Vielfaches von length ist.

Die Funktion ist besonders nützlich, wenn man mit mehrsprachigen Texten arbeitet und einzelne Zeichen korrekt auflisten, zählen oder verarbeiten möchte. Klassische Byte-Funktionen wie str_split() würden Multibyte-Sequenzen zerstückeln und dadurch ungültige Zeichenketten erzeugen. Mit grapheme_str_split() bleibt jedes Array-Element stets ein gültiger UTF-8-String.

Die Funktion ist Teil der Intl-Erweiterung (ICU-basiert) und muss entsprechend verfügbar sein.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Der zu teilende UTF-8-kodierte Eingabe-String.
$length	int	1	Anzahl der Graphem-Cluster pro Array-Element. Muss größer als 0 sein, sonst gibt die Funktion `false` zurück.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein Array von Strings zurück, wobei jeder String aus der angegebenen Anzahl Graphem-Cluster besteht. Gibt false zurück, wenn length kleiner oder gleich 0 ist oder der Eingabe-String kein gültiges UTF-8 ist.

Beispiele

Einfaches Aufteilen eines UTF-8-Strings in einzelne Grapheme

<?php
$text = 'Héllo';
$graphemes = grapheme_str_split($text);
print_r($graphemes);
// Vergleich: str_split würde Bytes zerstückeln
$bytes = str_split($text);
echo 'Anzahl Grapheme: ' . count($graphemes) . PHP_EOL;
echo 'Anzahl Bytes (str_split): ' . count($bytes) . PHP_EOL;

Array ( [0] => H [1] => é [2] => l [3] => l [4] => o ) Anzahl Grapheme: 5 Anzahl Bytes (str_split): 6

Aufteilen mit Emoji und Combining-Zeichen

<?php
// Emoji mit Hautfarbenmodifikator: Familie aus mehreren Codepoints
$text = "a\u{0301}e\u{0301}i"; // á, é, i als Basis + Combining Acute Accent
$graphemes = grapheme_str_split($text);
echo 'Anzahl Grapheme: ' . count($graphemes) . PHP_EOL;
foreach ($graphemes as $index => $g) {
    echo "[$index] => " . $g . ' (Bytes: ' . strlen($g) . ')' . PHP_EOL;
}

Anzahl Grapheme: 3 [0] => á (Bytes: 3) [1] => é (Bytes: 3) [2] => i (Bytes: 1)

Gruppenweise Aufteilung mit length-Parameter

<?php
$text = 'Hallo Welt';
$chunks = grapheme_str_split($text, 3);
print_r($chunks);

Array ( [0] => Hal [1] => lo [2] => Wel [3] => t )

// Wichtig · Fallstricke

Voraussetzung: Die Funktion erfordert die aktivierte Intl-Erweiterung (ext-intl). Ohne diese Erweiterung ist grapheme_str_split() nicht verfügbar. Prüfe die Verfügbarkeit mit function_exists('grapheme_str_split').

Ein Wert von length <= 0 führt zu einem Rückgabewert von false. Stelle daher sicher, dass der Parameter stets positiv ist. Für leere Strings wird ein Array mit einem einzigen leeren String zurückgegeben.

Im Gegensatz zu mb_str_split() (das auf Codepoints arbeitet) berücksichtigt grapheme_str_split() Combining Character Sequences korrekt und hält zusammengehörige Codepoints zusammen. Für die korrekte Verarbeitung von modernen Emoji-Sequenzen (z. B. Familien-Emoji aus mehreren Codepoints über ZWJ) kann das Verhalten je nach ICU-Version abweichen.

Siehe auch

grapheme_strlen grapheme_substr grapheme_strpos mb_str_split str_split preg_split