Add array_str_contains() function to standard library

Author: sepehrphpr

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_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/basic_functions_arginfo.h

@@ -0,0 +1,100 @@
+--TEST--
+array_str_contains() basic and edge cases tests
+--FILE--
+<?php
+
+echo "--- Basic Search ---\n";
+$fruits = ['apple', 'banana', 'cherry', 'pineapple', 'grape'];
+var_dump(array_str_contains($fruits, 'apple'));
+
+echo "\n--- Preserving String and Numeric Keys ---\n";
+$data = [
+    'first' => 'hello world',
+    10      => 'foo bar',
+    'third' => 'world domination',
+    20      => 'just php',
+];
+var_dump(array_str_contains($data, 'world'));
+
+echo "\n--- Non-string Values Ignored ---\n";
+$mixed = [
+    'a' => 'test 1',
+    'b' => 123,
+    'c' => null,
+    'd' => 'another test',
+    'e' => ['nested'],
+    'f' => true,
+];
+var_dump(array_str_contains($mixed, 'test'));
+
+echo "\n--- Empty Needle (Matches All String Elements) ---\n";
+$items = ['one', 2, 'three', false, ''];
+var_dump(array_str_contains($items, ''));
+
+echo "\n--- UTF-8 and Multi-byte Support ---\n";
+$persian = [
+    'سلام دنیا',
+    'خداحافظ دنیا',
+    'تست پی‌اچ‌پی',
+    'PHP 8.7 عالیه 🚀',
+    'یک ایموجی دیگر 🚀'
+];
+var_dump(array_str_contains($persian, 'دنیا'));
+var_dump(array_str_contains($persian, '🚀'));
+
+echo "\n--- Empty Haystack ---\n";
+var_dump(array_str_contains([], 'anything'));
+
+?>
+--EXPECT--
+--- Basic Search ---
+array(2) {
+  [0]=>
+  string(5) "apple"
+  [3]=>
+  string(9) "pineapple"
+}
+
+--- Preserving String and Numeric Keys ---
+array(2) {
+  ["first"]=>
+  string(11) "hello world"
+  ["third"]=>
+  string(18) "world domination"
+}
+
+--- Non-string Values Ignored ---
+array(2) {
+  ["a"]=>
+  string(6) "test 1"
+  ["d"]=>
+  string(12) "another test"
+}
+
+--- Empty Needle (Matches All String Elements) ---
+array(3) {
+  [0]=>
+  string(3) "one"
+  [2]=>
+  string(5) "three"
+  [4]=>
+  string(0) ""
+}
+
+--- UTF-8 and Multi-byte Support ---
+array(2) {
+  [0]=>
+  string(17) "سلام دنیا"
+  [1]=>
+  string(23) "خداحافظ دنیا"
+}
+array(2) {
+  [3]=>
+  string(18) "PHP 8.7 عالیه 🚀"
+  [4]=>
+  string(30) "یک ایموجی دیگر 🚀"
+}
+
+--- Empty Haystack ---
+array(0) {
+}