====== PHP RFC: str_contains ======
  * Version: 1
  * Date: 2020-02-17
  * Author: Philipp Tanlak, philipp.tanlak@gmail.com
  * Status: Implemented
  * First Published at: http://wiki.php.net/rfc/str_contains

===== 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 ''[[http://php.net/manual/en/function.strpos.php|strpos]]'' or ''[[http://php.net/manual/en/function.strstr.php|strstr]]''. Because this feature is such a common use-case in almost every project, it should deserve its own dedicated function: ''str_contains''.

Repurposing ''[[http://php.net/manual/en/function.strpos.php|strpos]]'' and ''[[http://php.net/manual/en/function.strstr.php|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''

<code php>
str_contains ( string $haystack , string $needle ) : bool
</code>

''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:
<code php>
<?php

str_contains("abc", "a"); // true
str_contains("abc", "d"); // false

// $needle is an empty string
str_contains("abc", "");  // true
str_contains("", "");     // true
</code>

Regarding empty string values as $needle:
<blockquote>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</blockquote>


===== 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 =====
<doodle title="Add str_contains as described" auth="philippta" voteType="single" closed="true">
   * Yes
   * No
</doodle>

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