PHP RFC: str_icontains

• Version: 0.1
• Date: 2025-06-13
• Author: Adam Cable, adamcable@gmail.com
• Status: In Draft
• First Published at: https://wiki.php.net/rfc/str_icontains

PHP 8.0 introduced the str_contains function, which provides a clear and concise way to determine if a string contains a given substring. This was a significant improvement over the traditional method of using strpos and checking the return value.

However, a common use case is to check for the presence of a substring in a case-insensitive manner. Currently, this requires using functions like stripos or converting both the haystack and needle to the same case using strtolower or strtoupper before comparison. These approaches can be less intuitive and more error-prone.

To address this, this RFC proposes the addition of a new function, str_icontains, as a case-insensitive counterpart to str_contains. The naming convention follows the precedent set by existing string functions, such as str_replace and its case-insensitive variant, str_ireplace.

It is proposed to add a new function to PHP:

function str_icontains(string $haystack, string $needle): bool

This function will return true if $needle is found in $haystack, with the comparison performed in a case-insensitive manner. The case-insensitivity will be based on ASCII case folding, which means it will correctly handle standard English alphabet characters (a-z, A-Z). This is consistent with the behaviour of other case-insensitive string functions in PHP, such as str_ireplace and stripos.

$string = "The quick brown fox jumps over the lazy dog.";
 
str_icontains($string, 'fox'); // true
str_icontains($string, 'FOX'); // true
str_icontains($string, 'Fox'); // true

Without str_icontains, a developer would have to write:

// Using stripos
stripos($string, 'FOX') !== false; // true
 
// Using strtolower
str_contains(strtolower($string), strtolower('FOX')); // true

The proposed str_icontains function is more readable and less susceptible to errors.

This RFC proposes the addition of a new function, so it does not introduce any backward-incompatible changes.

Next PHP 8.x (8.5).

Yes or no vote. 2/3 required to pass.

https://github.com/php/php-src/pull/18705

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

Prior discussion in May 2025: https://externals.io/message/127504

This RFC intentionally omits support for full UTF-8 case folding. The primary goal is to provide a direct, case-insensitive companion to the existing str_contains function, thereby achieving feature parity with other core string functions that operate on ASCII case folding (e.g., stripos, stristr). Introducing multibyte-aware functionality would be a significant extension beyond this scope and is better suited for a separate, more comprehensive proposal regarding multibyte string handling.

The name str_icontains was chosen over stri_contains to maintain consistency with the precedent set by str_ireplace.