Definition and Usage

PHP Version
8+

The str_contains() function checks if a string contains a specific substring.

Features

  • Returns true if the specified substring is found within the string; otherwise returns false.
  • Performs a case-sensitive comparison.
  • Introduced in PHP 8 and not available in earlier versions.

Basic Example

PHP 
$haystack = 'Hello! This is codingCourses.';
$needle = 'codingCourses';

if (str_contains($haystack, $needle)) {
    echo "The string contains '$needle'.";
} else {
    echo "The string does not contain '$needle'.";
}

// Output: The string contains 'codingCourses'.

Syntax

PHP 
str_contains(string $haystack, string $needle): bool

Parameters

Description of parameters used in the str_contains() function<
$haystack The string to be searched.
$needle The substring to search for.
This comparison is case-sensitive.

Return Values

Returns true if the specified substring is found within the target string, and false otherwise. The comparison is case-sensitive.

When the Search String Is an Empty String ('')

If the search string is an empty string (''), it is considered to exist at the end of every string. Therefore, using an empty string with str_contains() will always return true.

PHP 
if (str_contains('abc', '')) {
    echo 'Checking for an empty string always returns true.';
}

// Output: Checking for an empty string always returns true.

This behavior is based on the logical definition of strings. An empty string is conceptually present at both the beginning and end of any string. As a result, returning true for an empty search string is a consistent behavior not only in PHP but also in many other programming languages.

Things to Keep in Mind

The str_contains() function performs a case-sensitive comparison.

PHP 
$haystack = 'Hello, World!';

if (str_contains($haystack, 'world!')) {
    echo "The string contains 'world!'.";
} else {
    echo "Case does not match, so 'world!' was not found.";
}

// Output: Case does not match, so 'world!' was not found.

ince str_contains() was introduced in PHP 8, it is not available in earlier versions.

For projects running on PHP versions prior to 8, you can implement a simple polyfill as shown below.

Note:
The following example provides a basic polyfill for str_contains() in versions prior to PHP 8. It is not a complete implementation.
This polyfill works for simple use cases, but you may need to adjust it for your specific requirements, such as PHP version, performance, case-sensitivity, empty string handling, multibyte string support, and other scenarios.

PHP Polyfill example for str_contains() in PHP versions earlier than 8 
if (!function_exists('str_contains')) {
    /*
     * Example polyfill for str_contains()
     * Source: https://core.trac.wordpress.org/browser/trunk/src/wp-includes/compat.php#L423
     */
    function str_contains($haystack, $needle) {
        if ('' === $needle) {
            return true;
        }

        return false !== strpos($haystack, $needle);
    }
}

$haystack = 'Hello! This is codingCourses.';
$needle = 'codingCourses';

if (str_contains($haystack, $needle)) {
    echo "The string contains '$needle'.";
} else {
    echo "The string does not contain '$needle'.";
}

// Output: The string contains 'codingCourses'.

Code Explanation
The strpos() function finds the position of a substring within a string. It performs a case-sensitive search.

In PHP versions prior to 8, use strpos() to check whether a string contains a specific substring.

Practical Examples

The str_contains() function is useful for checking whether a string contains a specific substring. It is commonly applied in search functionality and string processing. Below are some example use cases.

Implementing a Search Feature

PHP 
$searchTerm = 'apple';
$text = 'I like apples and bananas.';

if (str_contains($text, $searchTerm)) {
    echo "The text contains the word '$searchTerm'.";
} else {
    echo "The text does not contain the word '$searchTerm'.";
}

// Output: The text contains the word 'apple'.

Filtering Unwanted Words

PHP 
$content = 'This sentence contains unwanted words.';
$unwantedWords = ['unwanted', 'bad', 'inappropriate'];

foreach ($unwantedWords as $word) {
    if (str_contains($content, $word)) {
        $content = str_replace($word, '***', $content);
    }
}

echo $content;

// Output: This sentence contains *** words.

Code Explanation
The foreach() loop iterates over arrays or objects for repeated processing.

Code Explanation
The str_replace() function is used to search for specific text within a string and replace it with another string.

Checking File Extensions (URL/Path Validation)

PHP 
$fileName = 'document.pdf';
$allowedExtensions = ['pdf', 'docx', 'txt'];

$fileExtension = pathinfo($fileName, PATHINFO_EXTENSION);

if (in_array($fileExtension, $allowedExtensions)) {
    echo 'The file extension is valid.';
} else {
    echo 'Invalid file extension.';
}

// Output: The file extension is valid.

Code Explanation
The in_array() function checks if a specific value exists in an array.

References

See also