[RFC] [Discussion] array_match

در تاریخ شنبه ۲۲ اوت ۲۰۲۶، ۱۶:۰۵ youkidearitai youkidearitai@gmail.com
نوشت:

‪2026年8月22日(土) 21:02 ‫سپهر محمودی‬‎ sepehrphpr@gmail.com:‬

Hi everyone,

As some of you may know, my previous RFC (array_search_range) faced
significant opposition and feedback. I have listened to the community and
officially withdrawn it. Thank you to everyone who took the time to review
it.

Today, I would like to introduce a new, much simpler, and highly focused
RFC: array_match()

Currently, if we want to filter an array to find elements containing a
specific substring, we have to rely on array_filter() combined with a
closure and strpos()/stripos(). This pattern is not only verbose but
also carries the performance overhead of executing a PHP closure for every
single array element.

I am proposing a native function to handle this efficiently in C:
array_match(array $array, string $needle, bool $ignore_case = false): array

This function preserves the original keys, safely casts values to
strings, and provides a clean, intent-revealing syntax. By implementing
this internally, we can significantly improve both readability and
execution speed compared to userland polyfills.

You can find all the use cases and examples detailed on the RFC page:
https://wiki.php.net/rfc/array_match

I look forward to hearing your thoughts and feedback on this proposal!

Best regards,
Sepehr Mahmoudi

Hi, Sepehr.

I have some questions.

• Why need this function? Is not enough in array_filter or array_find?
• In GitHub, There are many use cases in same name functions. from:
  https://github.com/search?q=array_match+language%3APHP&type=code
• In past RFC in str_icontains https://wiki.php.net/rfc/str_icontains
  was declind. So I don't think make sense that "case-insensitive" only
  ASCII now.

For your reference: In big OSS like php-src, We investigate use case first.

Regards
Yuya

--

Yuya Hamada (tekimen)

• https://tekitoh-memdhoi.info
• https://github.com/youkidearitai

---

Hi Yuya,

Thank you for taking the time to review the RFC and share your thoughts!

• Why need this function? Is not enough in array_filter or array_find?

While array_filter() is great, it requires a Closure for this task. For
large arrays, the overhead of calling a userland function for every single
element is significant. array_match() aims to provide a fast, native C
alternative for a very common operation.
As for array_find() (introduced in PHP 8.4), it only returns the first
matching element, whereas this proposal filters and returns all matching
elements.

• In GitHub, There are many use cases in same name functions. from:
  https://github.com/search?q=array_match+language%3APHP&type=code

I think the high number of custom array_match implementations in userland
actually proves how much developers need this functionality! However, you
bring up a valid point regarding potential name collisions (BC breaks). If
array_match conflicts with too many existing codebases, I am completely
open to bikeshedding the name (perhaps array_str_contains() or something
similar).

• In past RFC in str_icontains
  https://wiki.php.net/rfc/str_icontains
  was declind. So I don't think make sense that "case-insensitive" only
  ASCII now.

This is a very solid point. If the $ignore_case parameter brings up the
same ASCII/Unicode complexities that caused str_icontains to be declined,
I am more than happy to drop the $ignore_case parameter entirely. A
simple, fast, case-sensitive filter would still be highly valuable.

For your reference: In big OSS like php-src, We investigate use case
first.

Understood! I have included a few use cases (like log filtering, simple
search, and performance optimization over Closures) in the RFC. The GitHub
search link you provided is also a great testament to real-world usage.

Thanks again for your feedback, it is very helpful.

Best regards,
Sepehr

در تاریخ شنبه ۲۲ اوت ۲۰۲۶، ۱۹:۱۰ Ayesh Karunaratne ayesh@php.watch نوشت:

You can find all the use cases and examples detailed on the RFC page:
https://wiki.php.net/rfc/array_match

I look forward to hearing your thoughts and feedback on this proposal!

I'm thumbs down on this for a few reasons.

1. We already have str_contains function. It is more intuitive that
   a false strpos call, and it makes an array_filter function clean
   too.

array_filter($values, static fn($value) => str_contains($value, 'foo'));

2. I think this is a quite narrow use case. Even the RFC text example
   is arguably a poor use case for a str_contains check. When checking
   file extensions, it should be a str-ends-with check rather than a
   str-contains check.

3. Echoing what Yuya mentioned, the case sensitivity is quite
   difficult to reach a consensus on, for the same reasons why
   str_icontains RFC was declined. At this stage, I argue we should not
   add case-insensitive switches to any new functions.

4. Functions like this tend to be incomplete; someone else might argue
   for preserving array keys or filtering by array keys. We already have
   array_filter that can do all of it in any way the caller wants.

5. Finally, and somewhat opinionatedly, the word "match" resonates
   more with regular expressions. preg_match in PHP itself,
   String.match() in JS, re.match() in Python, etc to name a few.

Thank you.
Ayesh.

------‐-‐---

Hi Ayesh,

Thank you so much for your constructive feedback. I really appreciate the
points you raised!

Based on your suggestions and the feedback from the list, I have made
several major updates to the RFC. First, to avoid any confusion with
regular expressions, I have renamed the proposal and the function to
array_str_contains. I also removed the third parameter to keep the behavior
strictly aligned with the exact matching of str_contains(), and explicitly
stated that original array keys are preserved.

Regarding your valid point about using array_filter(), I have added a new
subsection under “Use Cases” specifically addressing “Why a native
function instead of array_filter?”. It highlights the ergonomics and the
performance benefits of avoiding closure overhead and context switching in
C. I also replaced the file extension example with a more practical URL
filtering scenario, as you suggested.

I would be grateful if you could take a look at the updated “Use Cases”
section. You can find the relocated and updated RFC page here:

https://wiki.php.net/rfc/array_str_contains

Thanks again for your time and for helping me improve this proposal.

Best regards,

Sepehr