Signatur
Beschreibung
mb_strcut() schneidet einen Teilstring aus $string heraus, wobei $start und $length in Bytes angegeben werden – im Gegensatz zu mb_substr(), das Zeichenpositionen verwendet. Der entscheidende Unterschied: mb_strcut() stellt sicher, dass kein Multibyte-Zeichen mitten entzwei geschnitten wird. Fällt die Byte-Grenze mitten in ein Multibyte-Zeichen, wird dieses Zeichen vollständig ausgelassen, sodass der Rückgabewert immer aus gültigen, vollständigen Zeichen besteht.
Die Funktion ist besonders nützlich, wenn ein String auf eine bestimmte Byte-Länge begrenzt werden muss (z. B. für Datenbankfelder oder Protokolle mit Byte-Limits), dabei aber keine ungültigen Zeichensequenzen entstehen sollen. Typische Anwendungsfälle sind etwa das Kürzen von UTF-8-Strings auf eine maximale Byte-Anzahl für ein VARCHAR-Feld.
Der Parameter $start kann negativ sein und zählt dann vom Ende des Strings in Bytes. Ist $length negativ, gibt die Funktion alle Bytes bis auf die letzten |$length| zurück. Wird $length weggelassen oder null übergeben, wird der Rest des Strings ab $start zurückgegeben.
Das optionale Argument $encoding bestimmt die Zeichenkodierung. Wird es nicht angegeben, verwendet die Funktion die mit mb_internal_encoding() gesetzte Kodierung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Der Eingabe-String, aus dem ein Teil extrahiert werden soll. | |
| $start Pflicht | int | Startposition in Bytes. Negative Werte zählen vom Ende des Strings rückwärts. | |
| $length | ?int | null | Maximale Länge des Ergebnisses in Bytes. Negative Werte schließen die letzten |$length| Bytes aus. null bedeutet: bis zum Ende des Strings. |
| $encoding | ?string | null | Zeichenkodierung des Eingabe-Strings, z. B. 'UTF-8'. Bei null wird mb_internal_encoding() verwendet. |
Rückgabewert
Beispiele
UTF-8-String auf maximale Byte-Anzahl kürzen
<?php
// Das Zeichen 'ä' benötigt in UTF-8 zwei Bytes
$text = 'Käse';
// mb_strcut auf 3 Bytes: 'K' (1 Byte) + 'ä' würde 2 Bytes brauchen => insgesamt 3
// 'ä' beginnt bei Byte 1 und endet bei Byte 2 (0-indiziert)
$result = mb_strcut($text, 0, 3, 'UTF-8');
echo $result; // 'Kä' (2 Zeichen, 3 Bytes)
echo '\n';
echo strlen($result); // 3 (Bytes)
String für ein Datenbankfeld auf Byte-Limit kürzen
<?php
// VARCHAR(10) in MySQL mit utf8mb4 = max. 10 Bytes
function trimToBytes(string $value, int $maxBytes, string $encoding = 'UTF-8'): string {
if (strlen($value) <= $maxBytes) {
return $value;
}
return mb_strcut($value, 0, $maxBytes, $encoding);
}
$title = '日本語テキスト'; // Jedes Zeichen = 3 Bytes in UTF-8
echo strlen($title) . ' Bytes gesamt\n'; // 21 Bytes
$safe = trimToBytes($title, 10);
echo $safe . '\n'; // '日本語' (9 Bytes, 3 Zeichen — 10 würde 'テ' halbieren)
echo strlen($safe) . ' Bytes\n'; // 9
Vergleich mit mb_substr
<?php
$text = 'Öl';
// mb_substr: 1 Zeichen ab Position 0 => 'Ö'
echo mb_substr($text, 0, 1, 'UTF-8') . '\n'; // Ö
// mb_strcut: 1 Byte ab Position 0 => 'Ö' ist 2 Bytes, wird ausgelassen => leerer String
echo mb_strcut($text, 0, 1, 'UTF-8') . '\n'; // (leer)
// mb_strcut: 2 Bytes ab Position 0 => 'Ö'
echo mb_strcut($text, 0, 2, 'UTF-8') . '\n'; // Ö
// Wichtig · Fallstricke
Unterschied zu mb_substr(): mb_substr() arbeitet mit Zeichenpositionen (Codepoints), mb_strcut() arbeitet mit Byte-Positionen. Welche Funktion besser geeignet ist, hängt vom Anwendungsfall ab: Byte-Limits → mb_strcut(), Zeichen-Limits → mb_substr().
Vorsicht bei negativen Werten: Negative $start-Werte werden in Bytes vom Stringende berechnet. Da Multibyte-Zeichen unterschiedlich viele Bytes belegen, kann das Ergebnis weniger Zeichen enthalten als erwartet, wenn die berechnete Byte-Position mitten in ein Zeichen fällt.
Encoding: Wird eine falsche oder nicht unterstützte Kodierung angegeben, kann mb_strcut() fehlschlagen oder unerwartete Ergebnisse liefern. Immer die tatsächliche Kodierung des Eingabe-Strings angeben.