Mit PHP 8.0 wurde die Funktion str_contains() eingeführt, die eine elegante Möglichkeit bietet, das Vorhandensein eines Teilstrings in einer Zeichenkette zu prüfen. Vor PHP 8 war dafür die Funktion strpos() in Kombination mit einem strikten Vergleich notwendig, was häufig zu schwer erkennbaren Fehlern führte. In diesem Tutorial lernst du die Syntax von str_contains(), siehst praktische Beispiele und erfährst, warum diese Funktion strpos() für einfache Substring-Prüfungen ablöst.
Der Einstieg beginnt mit der Funktionssignatur und den beiden Parametern, die str_contains() erwartet.
Syntax und Parameter
Die Funktion str_contains() erwartet zwei Parameter und gibt einen Boolean zurück. Der erste Parameter ist der sogenannte Haystack, also die Zeichenkette, in der gesucht wird. Der zweite Parameter ist die Needle, also der Teilstring, nach dem gesucht wird.
str_contains(string $haystack, string $needle): bool
Die Funktion gibt true zurück, wenn die Needle im Haystack enthalten ist, und false, wenn nicht. Ein wichtiges Detail: Wird ein leerer String als Needle übergeben, gibt str_contains() immer true zurück. Die Suche ist standardmäßig case-sensitive, unterscheidet also zwischen Groß- und Kleinschreibung.
Grundlegende Beispiele
Der einfachste Anwendungsfall ist die Prüfung, ob ein bestimmtes Wort in einem Text vorkommt. Das folgende Beispiel zeigt, wie str_contains() in einer if-Bedingung eingesetzt wird.
<?php
$text = 'PHP ist eine Programmiersprache';
if (str_contains($text, 'PHP')) {
echo 'Gefunden!';
}
Der Rückgabewert ist ein Boolean, der direkt in einer Bedingung verwendet werden kann. Es ist keine zusätzliche Vergleichsoperation nötig. Das macht den Code deutlich lesbarer als bei älteren Ansätzen mit strpos().
str_contains vs. strpos
Vor PHP 8 war strpos() die Standardmethode, um zu prüfen, ob ein Substring in einem String enthalten ist. Diese Methode hat jedoch eine bekannte Fehlerquelle, die mit der Position 0 zusammenhängt.
<?php
$email = 'nutzer@example.com';
/* Alte Methode mit strpos (fehleranfaellig) */
if (strpos($email, '@') !== false) {
echo 'Enthaelt @';
}
/* Neue Methode mit str_contains (klar und lesbar) */
if (str_contains($email, '@')) {
echo 'Enthaelt @';
}
Warum str_contains strpos vorzuziehen ist
Die Funktion strpos() gibt die numerische Position des ersten Vorkommens zurück oder false, wenn der Teilstring nicht gefunden wird. Das Problem entsteht, wenn der Teilstring am Anfang des Strings steht: strpos() gibt dann 0 zurück. Da 0 in PHP als falsy gilt, liefert ein einfacher if (strpos(...)) ein falsches Ergebnis. Deshalb war der strikte Vergleich !== false zwingend erforderlich. Wer diesen vergessen hat, erzeugte einen Bug, der schwer zu finden war.
Mit str_contains() entfällt dieses Problem vollständig. Die Funktion gibt ausschließlich true oder false zurück. Es ist kein strikter Vergleich nötig, und die Absicht des Codes ist sofort erkennbar.
flowchart TD
A["String prüfen"] --> B{"PHP-Version?"}
B --> C["8.0+: str_contains"]
B --> D["7.x: strpos !== false"]
C --> E{"Boolean"}
D --> F{"Position"}
E --> G["true: enthalten"]
E --> H["false: fehlt"]
F --> I["!== false: enthalten"]
F --> J["=== false: fehlt"]
Groß- und Kleinschreibung beachten
Die Funktion str_contains() arbeitet standardmäßig case-sensitive. Das bedeutet, dass die Schreibweise von Haystack und Needle exakt übereinstimmen muss. Der Suchbegriff php wird in einem String mit PHP nicht gefunden.
Case-insensitive Suche
Für eine Suche ohne Berücksichtigung der Groß- und Kleinschreibung gibt es keine eigene Funktion. Stattdessen werden Haystack und Needle vor dem Vergleich in Kleinbuchstaben umgewandelt. Für ASCII-Zeichen reicht strtolower(), für multibyte-fähige Zeichenketten wie UTF-8 empfiehlt sich mb_strtolower().
<?php
$text = 'Willkommen bei PHP-Space';
if (str_contains(strtolower($text), strtolower('php'))) {
echo 'Gefunden (ohne Beruecksichtigung der Schreibweise)';
}
Durch die Umwandlung beider Werte in Kleinbuchstaben wird ein case-insensitive Vergleich ermöglicht. Dieser Ansatz funktioniert zuverlässig und ist die empfohlene Methode in der PHP-Dokumentation.
Mehrere Teilstrings prüfen
In der Praxis muss häufig geprüft werden, ob ein String einen von mehreren möglichen Teilstrings enthält. Da str_contains() nur einen einzelnen Needle-Parameter akzeptiert, lässt sich die Prüfung mehrerer Begriffe mit einer Schleife umsetzen.
<?php
$nachricht = 'Bitte kontaktieren Sie unseren Support';
$suchbegriffe = ['Support', 'Hilfe', 'Kontakt'];
foreach ($suchbegriffe as $begriff) {
if (str_contains($nachricht, $begriff)) {
echo "Gefunden: $begriff";
}
}
Das Array $suchbegriffe enthält alle Begriffe, die geprüft werden sollen. Die foreach-Schleife iteriert über jeden Begriff und prüft mit str_contains(), ob er in der Nachricht vorkommt. Dieser Ansatz ist flexibel und lässt sich leicht um weitere Suchbegriffe erweitern. Wer nur wissen möchte, ob mindestens einer der Begriffe enthalten ist, kann die Logik in eine eigene Funktion auslagern und beim ersten Treffer true zurückgeben.
Verwandte Funktionen: str_starts_with und str_ends_with
Zusammen mit str_contains() wurden in PHP 8.0 zwei weitere String-Funktionen eingeführt: str_starts_with() und str_ends_with(). Alle drei Funktionen folgen demselben Muster mit Haystack und Needle und geben einen Boolean zurück.
Die Funktion str_starts_with() prüft, ob ein String mit einem bestimmten Teilstring beginnt. Die Funktion str_ends_with() prüft, ob ein String mit einem bestimmten Teilstring endet. Vor PHP 8 waren dafür Konstrukte mit substr() oder strpos() nötig, die deutlich weniger lesbar waren. Diese drei Funktionen bilden zusammen ein konsistentes Set für die gängigsten String-Prüfungen in PHP.
Fazit
Die Funktion str_contains() ist seit PHP 8.0 der empfohlene Weg, um zu prüfen, ob ein Teilstring in einer Zeichenkette enthalten ist. Sie ersetzt den fehleranfälligen Ansatz mit strpos() !== false durch eine klare, lesbare Syntax mit einem booleschen Rückgabewert. Die Funktion ist case-sensitive, was sich mit strtolower() oder mb_strtolower() umgehen lässt. In Kombination mit str_starts_with() und str_ends_with() bietet PHP 8 ein vollständiges Set an Funktionen für die Arbeit mit Teilstrings. Wer auf PHP 8.0 oder neuer setzt, sollte str_contains() konsequent anstelle von strpos() verwenden, um die Lesbarkeit und Zuverlässigkeit des Codes zu verbessern.
