Add array_str_contains() function to standard library

ext/standard/array.c

@@ -7371,3 +7371,53 @@ PHP_FUNCTION(array_combine)
 	} ZEND_HASH_FOREACH_END();
 }
 /* }}} */
+/* {{{ Filters array elements that contain a specific substring, preserving keys */
+PHP_FUNCTION(array_str_contains)
+{
+	HashTable *haystack;
+	zend_string *needle;
+	zval *val;
+	zend_string *key;
+	zend_ulong num_key;
+
+	ZEND_PARSE_PARAMETERS_START(2, 2)
+		Z_PARAM_ARRAY_HT(haystack)
+		Z_PARAM_STR(needle)
+	ZEND_PARSE_PARAMETERS_END();
+
+	array_init(return_value);
+
+	if (zend_hash_num_elements(haystack) == 0) {
+		return;
+	}
+
+	/* Empty needle matches every string element */
+	bool needle_is_empty = (ZSTR_LEN(needle) == 0);
+
+	ZEND_HASH_FOREACH_KEY_VAL(haystack, num_key, key, val) {
+		ZVAL_DEREF(val);
+
+		if (Z_TYPE_P(val) != IS_STRING) {
+			continue;
+		}
+
+		bool match = false;
+		if (needle_is_empty) {
+			match = true;
+		} else if (Z_STRLEN_P(val) >= ZSTR_LEN(needle)) {
+			if (php_memnstr(Z_STRVAL_P(val), ZSTR_VAL(needle), ZSTR_LEN(needle), Z_STRVAL_P(val) + Z_STRLEN_P(val))) {
+				match = true;
+			}
+		}
+
+		if (match) {
+			Z_TRY_ADDREF_P(val);
+			if (key) {
+				zend_hash_add_new(Z_ARRVAL_P(return_value), key, val);
+			} else {
+				zend_hash_index_add_new(Z_ARRVAL_P(return_value), num_key, val);
+			}
+		}
+	} ZEND_HASH_FOREACH_END();
+}
+/* }}} */

ext/standard/basic_functions.stub.php

@@ -1637,6 +1637,12 @@ function array_walk_recursive(array|object &$array, callable $callback, mixed $a
  */
 function in_array(mixed $needle, array $haystack, bool $strict = false): bool {}
 
+/**
+ * @param array $haystack
+ * @return array
+ */
+function array_str_contains(array $haystack, string $needle): array {}
+
 /**
  * @compile-time-eval
  */

ext/standard/php_array.h

@@ -71,4 +71,6 @@ ZEND_END_MODULE_GLOBALS(array)
 
 #define ARRAYG(v) ZEND_MODULE_GLOBALS_ACCESSOR(array, v)
 
+PHP_FUNCTION(array_str_contains);
+
 #endif /* PHP_ARRAY_H */

ext/standard/tests/array/array_str_contains.phpt

@@ -0,0 +1,85 @@
+--TEST--
+array_str_contains() basic functionality and edge cases
+--FILE--
+<?php
+
+$fruits = ["apple", "banana", "cherry", "date", "elderberry"];
+
+echo "--- Basic Search ---\n";
+var_dump(array_str_contains($fruits, "an"));
+var_dump(array_str_contains($fruits, "berry"));
+var_dump(array_str_contains($fruits, "xyz"));
+
+echo "\n--- Key Preservation ---\n";
+$assoc = ["a" => "first item", "b" => "second item", "c" => "third"];
+var_dump(array_str_contains($assoc, "item"));
+
+echo "\n--- Empty Needle ---\n";
+$emptyNeedleTest = ["foo", "bar", "baz"];
+var_dump(array_str_contains($emptyNeedleTest, ""));
+
+echo "\n--- UTF-8 and Multi-byte Support ---\n";
+$multibyte = [
+    "سلام دنیا",
+    "خداحافظ دنیا",
+    "PHP 8.7",
+    "PHP 8.7 café 🚀",
+    "یک ایموجی دیگر 🚀",
+];
+var_dump(array_str_contains($multibyte, "دنیا"));
+var_dump(array_str_contains($multibyte, "🚀"));
+
+echo "\n--- Empty Haystack ---\n";
+var_dump(array_str_contains([], "needle"));
+
+?>
+--EXPECT--
+--- Basic Search ---
+array(2) {
+  [1]=>
+  string(6) "banana"
+  [4]=>
+  string(10) "elderberry"
+}
+array(1) {
+  [4]=>
+  string(10) "elderberry"
+}
+array(0) {
+}
+
+--- Key Preservation ---
+array(2) {
+  ["a"]=>
+  string(10) "first item"
+  ["b"]=>
+  string(11) "second item"
+}
+
+--- Empty Needle ---
+array(3) {
+  [0]=>
+  string(3) "foo"
+  [1]=>
+  string(3) "bar"
+  [2]=>
+  string(3) "baz"
+}
+
+--- UTF-8 and Multi-byte Support ---
+array(2) {
+  [0]=>
+  string(17) "سلام دنیا"
+  [1]=>
+  string(23) "خداحافظ دنیا"
+}
+array(2) {
+  [3]=>
+  string(18) "PHP 8.7 café 🚀"
+  [4]=>
+  string(31) "یک ایموجی دیگر 🚀"
+}
+
+--- Empty Haystack ---
+array(0) {
+}