str_contains View as Markdown

Introduction

str_contains checks if a string is contained in another string and returns a boolean value (true/false) whether or not the string was found.

The typical way to check if a string is contained in another is mostly done by using the functions strpos or strstr. Because this feature is such a common use-case in almost every project, it should deserve its own dedicated function: str_contains.

Repurposing strpos and strstr for this use-case has a few down sides. Either, they are:

• not very intuitive for a reader
• easy to get wrong (especially with the !== comparison)
• or hard to remember for new PHP developers.

Because of that, many PHP frameworks offer a helper function for this behavior, because it is so ubiquitous. This indicates the significance and the necessity pretty well.

Proposal

This RFC proposes the new basic function: str_contains

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

str_contains takes a $haystack and a $needle as arguments, checks if $needle is found in $haystack and returns a boolean value (true/false) whether or not the $needle was found.

The proposed function as code:

<?php
 
str_contains("abc", "a"); // true
str_contains("abc", "d"); // false
 
// $needle is an empty string
str_contains("abc", "");  // true
str_contains("", "");     // true

Regarding empty string values as $needle:

As of PHP 8, behavior of “” in string search functions is well defined, and we consider “” to occur at every position in the string, including one past the end. As such, both of these will (or at least should) return true. The empty string is contained in every string. - Nikita Popov

Case-insensitivity and multibyte strings

In a recent discussion in the internals mailing list, we came to the conclusion, there is no need for a multibyte variant of this function (e.g. mb_str_contains). The reason behind this is: A multibyte variant of this function would behave no different than the non-multibyte function. Multibyte variants behave differently when the offset/position has relevance at which the string was found. As this is not the case for this function, there is no need for that.

Concerning the case-insensitivity for this function: This might be a feature for the future, as the relevance for that is much less compared to the case-sensitive function. With that in mind, the only valid variants would be str_contains/mb_str_icontains. I assume PHP developers would be confused if this RFC offered such inconsistent variants of this function, so it's better to start small and iterate upon that.

Backward Incompatible Changes

No backwards incompatible changes inside php itself.

There might be incompatibilities, if this function was implemented in the user-land code. But this issue would be noticed by the developer quickly as such global functions are added rather early in the application boot process. This is also the reason why this feature is proposed for PHP 8, as developers test their frameworks against new major versions more specifically.

Proposed PHP Version(s)

PHP 8

Voting

Vote: Add str_contains as described — Yes: 43 · No: 9 (closed)

Implementation

The str_contains function has been implemented in this pull request: https://github.com/php/php-src/pull/5179