# RFC: Add case-insensitive version of str_contains

- Status: Declined
- Authors: Adam Cable, adamcable@gmail.com
- Date: 2025-07-01
- Version: 0.3
- Original: https://wiki.php.net/rfc/str_icontains
- Page: https://externals.io/rfc/str_icontains
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### str_icontains (closed)

Yes: 6 · No: 11

Voters: alec (Yes), ashnazg (Yes), ayesh (No), bwoebi (Yes), crell (No), cschneid (No), daniels (No), derick (No), devnexen (No), ericmann (No), galvao (Yes), heiglandreas (No), mfonda (Yes), rasmus (No), seld (Yes), thorstenr (No), timwolla (No)

## Discussions on the mailing list

- [Proposal for a new basic function: str_contains](https://externals.io/message/108562.md) — started on 2020-02-14, 22 messages
- [Adding in a case-insensitive version of str_contains](https://externals.io/message/127504.md) — started on 2025-05-29, 10 messages
- [\[RFC\] str_icontains](https://externals.io/message/127667.md) — started on 2025-06-15, 9 messages
- [\[VOTE\] str_icontains](https://externals.io/message/127810.md) — started on 2025-07-01, 9 messages

---

## Introduction

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.

## Proposal

It is proposed to add a new function to PHP:

```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.

### Use Cases

#### Example 1: Basic Usage

```php
$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
```

#### Example 2: Comparison with current methods

Without str\_icontains, a developer would have to write:

```php
// 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.

## Why wasn't this included with str\_contains?

I have reviewed the previous discussions and RFCs surrounding the initial introduction of str\_contains. The reason a case-insensitive version was not included at that time was twofold:

- Limited Functional Gain: Some community members felt that the case-insensitive variant did not provide a significant enough improvement over existing userland code (e.g., strtolower($haystack)) to warrant its inclusion in the PHP core.

- Risk of RFC Failure: The debate over whether to include a case-insensitive version, particularly with the complexities of ASCII vs. UTF-8 case folding, was a contentious topic that could have jeopardised the entire str\_contains RFC from passing. The primary goal was to get a simple, much-needed function into the core.

Now that str\_contains is a stable and widely used function in the PHP core, adding a case-insensitive version seems to me to be a logical next step. It creates a complete and consistent set of functions, mirroring the relationships between strpos -&gt; stripos and strstr -&gt; stristr. While the ASCII-only folding remains a limitation, this behaviour is consistent with its sibling functions, providing a predictable and familiar experience for developers.

Having a UTF-8 supported version of this suite of functions that matches on the lower/upper case variant of each Unicode code point should of course be a goal, but I believe the inclusion of this function in its current form, aligned with its siblings, is better than not having the function at all.

## Backward Incompatible Changes

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

## Proposed PHP Version(s)

Next PHP 8.x (8.5).

## Proposed Voting Choices

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

**Vote: str\_icontains** — Yes: 6 · No: 11 (closed)

## Patches and Tests

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

## Implementation

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)

## References

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

Original str\_contains RFC: [https://wiki.php.net/rfc/str\_contains](https://externals.io/rfc/str_contains)

Original str\_contains discussion: <https://externals.io/message/108562>

## Rejected Features

### UTF-8 Support

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.

### stri\_contains Naming

The name str\_icontains was chosen over stri\_contains to maintain consistency with the precedent set by str\_ireplace.
