substr_compare — Funktion · PHP-Referenz

Signatur

substr_compare(string $haystack, string $needle, int $offset, ?int $length = null, bool $case_insensitive = false): int|false

Beschreibung

substr_compare vergleicht einen Ausschnitt des Strings $haystack mit dem String $needle. Der Vergleich beginnt an der durch $offset angegebenen Position in $haystack. Ein negativer $offset-Wert zählt vom Ende des Strings rückwärts. Die Funktion ist binärsicher, d. h. sie verarbeitet auch Binärdaten korrekt und berücksichtigt Nullbytes.

Der optionale Parameter $length begrenzt die Anzahl der verglichenen Zeichen. Wird er weggelassen oder auf null gesetzt, wird die Länge des längeren der beiden verglichenen Bereiche verwendet. Mit $case_insensitive = true kann ein Vergleich ohne Berücksichtigung der Groß-/Kleinschreibung durchgeführt werden.

Die Funktion eignet sich hervorragend, wenn man prüfen möchte, ob ein String an einer bestimmten Stelle mit einem bestimmten Muster beginnt oder endet — ohne vorher mit substr einen neuen Teilstring erzeugen zu müssen, was Speicher spart und den Code kompakter hält.

Häufige Anwendungsfälle sind z. B. das Prüfen von Dateiendungen, das Validieren von Protokoll-Präfixen oder das Vergleichen von Datenpaketen in Netzwerkprotokollen.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der Haupt-String, aus dem der Teilstring verglichen wird.
$needle Pflicht	string		Der String, mit dem der Ausschnitt aus `$haystack` verglichen wird.
$offset Pflicht	int		Die Startposition im `$haystack`. Ein negativer Wert zählt vom Ende des Strings rückwärts (ab PHP 7.1.0 vollständig unterstützt).
$length	?int	null	Die maximale Anzahl der zu vergleichenden Zeichen. Ist `null` oder nicht angegeben, wird automatisch die Länge des längeren verglichenen Bereichs verwendet.
$case_insensitive	bool	false	Wenn `true`, wird der Vergleich ohne Rücksicht auf Groß-/Kleinschreibung durchgeführt (ähnlich wie `strcasecmp`).

Rückgabewert

Typ

int|false

Beschreibung

Gibt 0 zurück, wenn die verglichenen Teilstrings gleich sind. Ein negativer Wert bedeutet, dass der Teilstring von $haystack lexikografisch kleiner als $needle ist; ein positiver Wert bedeutet, dass er größer ist.

Gibt false zurück, wenn $offset größer als die Länge von $haystack ist oder wenn $length negativ ist und kleiner als die Länge von $needle. Achtung: Da 0 (gleich) und false bei losem Vergleich (==) identisch sind, muss mit === geprüft werden.

Beispiele

Prüfen ob ein String mit einer bestimmten Endung endet

<?php
$filename = 'bericht_2024.pdf';
$extension = '.pdf';

// Negativer Offset: zählt vom Ende des Strings
$result = substr_compare($filename, $extension, -strlen($extension));

if ($result === 0) {
    echo "Die Datei hat die Endung .pdf.";
} else {
    echo "Keine PDF-Datei.";
}

Die Datei hat die Endung .pdf.

Vergleich eines Teilstrings ab einer bestimmten Position

<?php
$url = 'https://programmierung.net/php';
$protokoll = 'https';

// Vergleich ab Position 0, Länge von 'https'
$result = substr_compare($url, $protokoll, 0, strlen($protokoll));

if ($result === 0) {
    echo "Die URL verwendet HTTPS.";
} else {
    echo "Kein HTTPS.";
}

Die URL verwendet HTTPS.

Groß-/Kleinschreibungsunabhängiger Vergleich

<?php
$text = 'Hallo Welt';
$search = 'hallo';

$result = substr_compare($text, $search, 0, strlen($search), true);

if ($result === 0) {
    echo "Beginnt mit 'hallo' (unabhängig von Groß-/Kleinschreibung).";
} else {
    echo "Beginnt nicht mit 'hallo'.";
}

Beginnt mit 'hallo' (unabhängig von Groß-/Kleinschreibung).

Fallstrick: Vergleich des Rückgabewerts mit false

<?php
$result = substr_compare('kurz', 'test', 100); // Offset > Stringlänge

// FALSCH: loser Vergleich, 0 == false ist true!
if ($result == false) {
    echo "Fehler oder gleich? Unklar!";
}

// RICHTIG: strikter Vergleich
if ($result === false) {
    echo "Fehler: Offset außerhalb des Strings.";
} elseif ($result === 0) {
    echo "Strings sind gleich.";
}

Fehler: Offset außerhalb des Strings.

// Wichtig · Fallstricke

Wichtiger Fallstrick: Der Rückgabewert 0 (Strings gleich) und false (Fehler) dürfen nie mit dem losen Vergleichsoperator == geprüft werden, da 0 == false in PHP true ergibt. Verwende immer den strikten Vergleich ===.

Ab PHP 8.0 löst ein ungültiger $offset (größer als die Stringlänge) eine ValueError-Exception aus, anstatt false zurückzugeben. In PHP 7.x wurde noch false zurückgegeben und eine E_WARNING ausgelöst.

Negative $offset-Werte werden seit PHP 7.1.0 vollständig und korrekt unterstützt. In älteren Versionen konnte das Verhalten abweichen.

Siehe auch

strcmp strncmp strcasecmp substr strpos str_ends_with str_starts_with