strcspn — Funktion · PHP-Referenz

Signatur

strcspn(string $string, string $characters, int $offset = 0, int $length = PHP_INT_MAX): int

Beschreibung

strcspn ("string complement span") durchsucht den String $string ab dem Anfang (bzw. ab $offset) und zählt, wie viele aufeinanderfolgende Zeichen nicht in der Zeichenmaske $characters enthalten sind. Sobald ein Zeichen aus der Maske gefunden wird, stoppt die Zählung und die bisherige Länge wird zurückgegeben.

Die Funktion ist das Gegenstück zu strspn, das zählt, wie viele Zeichen in der Maske enthalten sind. strcspn eignet sich hervorragend dazu, Trennzeichen zu finden oder Eingaben auf unerwünschte Zeichen zu prüfen – etwa um herauszufinden, wo ein Sonderzeichen erstmals auftritt.

Mit den optionalen Parametern $offset und $length kann ein Teilbereich des Strings untersucht werden. Negative Werte für $offset starten vom Ende des Strings, ein negativer $length-Wert schließt Zeichen vom Ende aus.

Die Funktion arbeitet byte-weise und ist daher nicht multibyte-sicher. Bei Strings mit Multi-Byte-Kodierungen (z. B. UTF-8) sollten die mbstring-Funktionen bevorzugt werden.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Der zu untersuchende Eingabe-String.
$characters Pflicht	string		Die Zeichenmaske – eine Menge von Zeichen, nach denen gesucht wird. Sobald eines dieser Zeichen im String gefunden wird, stoppt die Zählung.
$offset	int	0	Startposition im String. Negative Werte zählen vom Ende des Strings rückwärts.
$length	int	PHP_INT_MAX	Maximale Anzahl zu prüfender Zeichen ab `$offset`. Ein negativer Wert schließt die entsprechende Anzahl Zeichen vom Ende des Strings aus.

Rückgabewert

Typ

int

Beschreibung

Gibt die Länge (Anzahl der Bytes) des anfänglichen Teilstrings zurück, der kein Zeichen aus $characters enthält. Ist das erste Zeichen bereits in der Maske enthalten, wird 0 zurückgegeben. Enthält der String gar kein Zeichen aus der Maske, wird die Länge des gesamten geprüften Bereichs zurückgegeben.

Beispiele

Grundlegende Verwendung: Position eines Sonderzeichens finden

<?php
$string = 'Hallo, Welt!';
$maske  = ',!?.';

$laenge = strcspn($string, $maske);

echo "Länge bis zum ersten Sonderzeichen: $laenge\n";
echo "Erstes Sonderzeichen an Position: $laenge\n";
echo "Teilstring davor: " . substr($string, 0, $laenge) . "\n";

Länge bis zum ersten Sonderzeichen: 5 Erstes Sonderzeichen an Position: 5 Teilstring davor: Hallo

Eingabevalidierung: Prüfen ob unerlaubte Zeichen vorhanden sind

<?php
function enthaeltNurErlaubteZeichen(string $eingabe, string $verboten): bool {
    // Wenn strcspn die gesamte Länge zurückgibt, wurden keine verbotenen Zeichen gefunden
    return strcspn($eingabe, $verboten) === strlen($eingabe);
}

$benutzername = 'MaxMustermann';
$verboten     = '<>\'";&';

if (enthaeltNurErlaubteZeichen($benutzername, $verboten)) {
    echo "Benutzername ist gültig.\n";
} else {
    echo "Benutzername enthält ungültige Zeichen!\n";
}

$boserName = 'Max<script>';
if (enthaeltNurErlaubteZeichen($boserName, $verboten)) {
    echo "Benutzername ist gültig.\n";
} else {
    echo "Benutzername enthält ungültige Zeichen!\n";
}

Benutzername ist gültig. Benutzername enthält ungültige Zeichen!

Verwendung mit offset und length

<?php
$string = 'abc123def456';

// Ab Position 3 prüfen, wie viele Zeichen keine Buchstaben sind
$laenge = strcspn($string, 'abcdefghijklmnopqrstuvwxyz', 3, 6);

echo "Nicht-Buchstaben ab Offset 3: $laenge\n";
// Teilbereich: '123def' → '123' enthält keine Buchstaben → Ergebnis: 3

Nicht-Buchstaben ab Offset 3: 3

// Wichtig · Fallstricke

Byte-Orientierung: strcspn arbeitet byte-weise und ist nicht multibyte-sicher. Bei UTF-8-kodierten Strings mit Umlauten oder anderen Multi-Byte-Zeichen kann die Funktion fehlerhafte Ergebnisse liefern. In solchen Fällen sollte auf passende Funktionen der mbstring-Erweiterung zurückgegriffen werden.

Leere Zeichenmaske: Wenn $characters ein leerer String ist, gibt strcspn die Länge des gesamten Strings (bzw. des geprüften Bereichs) zurück, da kein verbotenes Zeichen existiert.

Kein Ersatz für Sicherheitsfunktionen: Für eine vollständige Eingabebereinigung, etwa zum Schutz vor XSS oder SQL-Injection, sollte strcspn nicht als alleinige Maßnahme eingesetzt werden. Hierfür sind htmlspecialchars, filter_var oder vorbereitete SQL-Anweisungen (Prepared Statements) geeigneter.

Siehe auch

strspn strpbrk strpos substr preg_match