Filtering an array down to the values that contain a substring is a common job, and today you write it with array_filter() and a closure, or with a foreach loop. Sepehr Mahmoudi's RFC adds array_str_contains(), a native function that does it in one call and skips the per-element callback.

How it works

The function takes an array and a needle, and returns the elements whose value contains the needle:

function array_str_contains(array $haystack, string $needle): array {}

Here is how you'd write it today, next to the proposed version:

$logs = [
    200 => 'INFO: Application started',
    201 => 'ERROR: Database timeout',
    202 => 'WARNING: CPU load high',
    203 => 'ERROR: Invalid user input',
];

// Today
$errors = array_filter($logs, fn ($line) => str_contains($line, 'ERROR:'));

// With the RFC
$errors = array_str_contains($logs, 'ERROR:');

// [201 => 'ERROR: Database timeout', 203 => 'ERROR: Invalid user input']

A few details from the RFC:

  • The match is case-sensitive, the same as str_contains(), so 'Products' won't match 'products'.
  • It compares bytes, so UTF-8 text and emoji work without ext/intl.
  • Non-string values are cast to strings first, so the integer 100 matches the needle '100'.
  • Keys are preserved in the result.

The RFC illustrates the behavior with a userland polyfill: loop over the array, cast each value to a string, and keep the ones where str_contains() returns true.

The RFC also reports a scan of 200 popular packages. It found 32 places doing something related, but at least 15 of those carry extra logic, so up to 17 could switch over directly.

What it means for existing code

Nothing breaks. The RFC lists no backward incompatible changes, since it only adds a new function.

Where it stands

The RFC targets PHP 8.7. The page lists it as Under Discussion, while the wiki's RFC index still files it under drafts. An implementation is up in php-src PR #23512, and no vote has been scheduled.