Signatur
Beschreibung
grapheme_extract() ermöglicht es, präzise Teilstrings aus UTF-8-Texten zu extrahieren, indem es mit echten Graphem-Clustern arbeitet – also mit den visuell wahrnehmbaren Zeichen, die aus einem oder mehreren Unicode-Codepunkten bestehen können (z. B. Basiszeichen + diakritische Zeichen). Damit verhält sich die Funktion korrekt bei kombinierten Zeichen, Emoji-Sequenzen und anderen mehrcodepunktigen Graphemen.
Der Parameter type steuert, wie size interpretiert wird: Als Anzahl von Graphem-Clustern (GRAPHEME_EXTR_COUNT), als maximale Byte-Länge (GRAPHEME_EXTR_MAXBYTES) oder als maximale Anzahl von Codepunkten (GRAPHEME_EXTR_MAXCHARS). Dadurch ist die Funktion sehr flexibel für unterschiedliche Anwendungsfälle wie Anzeige, Speicher- oder Übertragungslimits.
Der optionale Parameter next wird als Referenz übergeben und enthält nach dem Aufruf die Byte-Position im ursprünglichen String, an der die Extraktion geendet hat. Dies ermöglicht effizientes iteratives Durchlaufen eines UTF-8-Textes in aufeinanderfolgenden Extraktionsschritten.
Die Funktion ist Teil der intl-Erweiterung (International Components for Unicode) und benötigt daher eine PHP-Installation mit aktivierter ICU-Unterstützung. Sie ist besonders wertvoll beim Implementieren von Texttrunkierung, Paginations-Logik oder überall dort, wo korrektes Unicode-Handling unerlässlich ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $haystack Pflicht | string | Der UTF-8-kodierte Eingabestring, aus dem Graphem-Cluster extrahiert werden sollen. | |
| $size Pflicht | int | Die Menge an Daten, die extrahiert werden soll. Interpretation hängt vom type-Parameter ab: Anzahl Grapheme, maximale Bytes oder maximale Codepunkte. |
|
| $type | int | GRAPHEME_EXTR_COUNT | Bestimmt, wie size interpretiert wird. Mögliche Werte: GRAPHEME_EXTR_COUNT (Anzahl Graphem-Cluster), GRAPHEME_EXTR_MAXBYTES (maximale Byte-Anzahl), GRAPHEME_EXTR_MAXCHARS (maximale Anzahl Unicode-Codepunkte). |
| $start | int | 0 | Byte-Offset im haystack, ab dem die Extraktion beginnen soll. Muss auf den Anfang eines gültigen UTF-8-Zeichens zeigen. |
| $next | int | null | Wird als Referenz übergeben und enthält nach dem Aufruf den Byte-Offset im haystack, der auf das erste Zeichen nach dem extrahierten Bereich zeigt. Nützlich für iterative Verarbeitung. |
Rückgabewert
false zurückgegeben.Beispiele
Extraktion nach Anzahl von Graphem-Clustern
<?php
// String mit kombinierten Unicode-Zeichen (e + kombinierender Akzent)
$text = "cafe\u{0301} und Stra\u{00DF}e";
// Die ersten 5 Graphem-Cluster extrahieren
$result = grapheme_extract($text, 5, GRAPHEME_EXTR_COUNT);
echo $result . PHP_EOL;
// Ausgabe: café u (5 Grapheme: c, a, f, é, Leerzeichen)Iterative Extraktion mit $next für Paginierung
<?php
$text = "Héllo Wörld! 😀🎉";
$offset = 0;
$chunkSize = 3;
while ($offset < strlen($text)) {
$chunk = grapheme_extract($text, $chunkSize, GRAPHEME_EXTR_COUNT, $offset, $next);
if ($chunk === false) {
break;
}
echo "Chunk: [{$chunk}]" . PHP_EOL;
$offset = $next;
}Extraktion mit Byte-Limit (GRAPHEME_EXTR_MAXBYTES)
<?php
// Maximal 10 Bytes extrahieren, aber ohne Grapheme zu zerteilen
$text = "Ünïcödé";
$result = grapheme_extract($text, 10, GRAPHEME_EXTR_MAXBYTES);
echo $result . PHP_EOL;
echo "Byte-Länge: " . strlen($result) . PHP_EOL;// Wichtig · Fallstricke
Achtung: Der Parameter start ist ein Byte-Offset, kein Graphem- oder Zeichen-Offset. Ein falscher Offset, der mitten in ein Multibyte-Zeichen zeigt, führt zu false als Rückgabewert.
Die Funktion setzt die intl-PHP-Erweiterung voraus. Falls intl nicht verfügbar ist, ist auch grapheme_extract() nicht definiert. Prüfe mit extension_loaded('intl'), ob die Erweiterung aktiv ist.
Im Gegensatz zu mb_substr() arbeitet grapheme_extract() mit echten Graphem-Clustern gemäß Unicode-Standard, was bei Texten mit kombinierten Zeichen oder Emoji-Sequenzen zu unterschiedlichen Ergebnissen führen kann. Für korrektes Unicode-Handling ist grapheme_extract() die zuverlässigere Wahl.