General: Introduce polyfills for new array related functions in PHP 8.4.

PHP 8.4 introduced four new functions to provide a common way to more easily perform common operations on arrays.

- `array_find()`: https://www.php.net/manual/en/function.array-find.php
- `array_find_key()`: https://www.php.net/manual/en/function.array-find-key.php
- `array_all()`: https://www.php.net/manual/en/function.array-all.php
- `array_any()`: https://www.php.net/manual/en/function.array-any.php

These functions are now polyfilled making them available on all supported versions of PHP (currently 7.2+).

Props Soean, swissspidy, TobiasBg, ayeshrajans, mukesh27, joemcgill.
Fixes #62558.

git-svn-id: https://develop.svn.wordpress.org/trunk@59783 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/compat.php

@@ -549,6 +549,98 @@ if ( ! function_exists( 'str_ends_with' ) ) {
 	}
 }
 
+if ( ! function_exists( 'array_find' ) ) {
+	/**
+	 * Polyfill for `array_find()` function added in PHP 8.4.
+	 *
+	 * Searches an array for the first element that passes a given callback.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param array    $array    The array to search.
+	 * @param callable $callback The callback to run for each element.
+	 * @return mixed|null The first element in the array that passes the `$callback`, otherwise null.
+	 */
+	function array_find( array $array, callable $callback ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.arrayFound
+		foreach ( $array as $key => $value ) {
+			if ( $callback( $value, $key ) ) {
+				return $value;
+			}
+		}
+
+		return null;
+	}
+}
+
+if ( ! function_exists( 'array_find_key' ) ) {
+	/**
+	 * Polyfill for `array_find_key()` function added in PHP 8.4.
+	 *
+	 * Searches an array for the first key that passes a given callback.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param array    $array    The array to search.
+	 * @param callable $callback The callback to run for each element.
+	 * @return int|string|null The first key in the array that passes the `$callback`, otherwise null.
+	 */
+	function array_find_key( array $array, callable $callback ) { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.arrayFound
+		foreach ( $array as $key => $value ) {
+			if ( $callback( $value, $key ) ) {
+				return $key;
+			}
+		}
+
+		return null;
+	}
+}
+
+if ( ! function_exists( 'array_any' ) ) {
+	/**
+	 * Polyfill for `array_any()` function added in PHP 8.4.
+	 *
+	 * Checks if any element of an array passes a given callback.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param array    $array    The array to check.
+	 * @param callable $callback The callback to run for each element.
+	 * @return bool True if any element in the array passes the `$callback`, otherwise false.
+	 */
+	function array_any( array $array, callable $callback ): bool { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.arrayFound
+		foreach ( $array as $key => $value ) {
+			if ( $callback( $value, $key ) ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+}
+
+if ( ! function_exists( 'array_all' ) ) {
+	/**
+	 * Polyfill for `array_all()` function added in PHP 8.4.
+	 *
+	 * Checks if all elements of an array pass a given callback.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param array    $array    The array to check.
+	 * @param callable $callback The callback to run for each element.
+	 * @return bool True if all elements in the array pass the `$callback`, otherwise false.
+	 */
+	function array_all( array $array, callable $callback ): bool { // phpcs:ignore Universal.NamingConventions.NoReservedKeywordParameterNames.arrayFound
+		foreach ( $array as $key => $value ) {
+			if ( ! $callback( $value, $key ) ) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+}
+
 // IMAGETYPE_AVIF constant is only defined in PHP 8.x or later.
 if ( ! defined( 'IMAGETYPE_AVIF' ) ) {
 	define( 'IMAGETYPE_AVIF', 19 );

tests/phpunit/tests/compat/arrayAll.php

@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * @group compat
+ *
+ * @covers ::array_all
+ */
+class Test_Compat_arrayAll extends WP_UnitTestCase {
+
+	/**
+	 * Test that array_all() is always available (either from PHP or WP).
+	 *
+	 * @ticket 62558
+	 */
+	public function test_array_all_availability() {
+		$this->assertTrue( function_exists( 'array_all' ) );
+	}
+
+	/**
+	 * @dataProvider data_array_all
+	 *
+	 * @ticket 62558
+	 *
+	 * @param bool $expected The expected value.
+	 * @param array $arr The array.
+	 * @param callable $callback The callback.
+	 */
+	public function test_array_all( bool $expected, array $arr, callable $callback ) {
+		$this->assertSame( $expected, array_all( $arr, $callback ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public function data_array_all(): array {
+		return array(
+			'empty array'   => array(
+				'expected' => true,
+				'arr'      => array(),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'no match'      => array(
+				'expected' => false,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'not all match' => array(
+				'expected' => false,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 0 === $value % 2;
+				},
+			),
+			'match'         => array(
+				'expected' => true,
+				'arr'      => array( 2, 4, 6 ),
+				'callback' => function ( $value ) {
+					return 0 === $value % 2;
+				},
+			),
+			'key match'     => array(
+				'expected' => true,
+				'arr'      => array(
+					'a' => 2,
+					'b' => 4,
+					'c' => 6,
+				),
+				'callback' => function ( $value, $key ) {
+					return strlen( $key ) === 1;
+				},
+			),
+		);
+	}
+}

tests/phpunit/tests/compat/arrayAny.php

@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * @group compat
+ *
+ * @covers ::array_any
+ */
+class Test_Compat_arrayAny extends WP_UnitTestCase {
+
+	/**
+	 * Test that array_any() is always available (either from PHP or WP).
+	 *
+	 * @ticket 62558
+	 */
+	public function test_array_any_availability() {
+		$this->assertTrue( function_exists( 'array_any' ) );
+	}
+
+	/**
+	 * @dataProvider data_array_any
+	 *
+	 * @ticket 62558
+	 *
+	 * @param bool $expected The expected value.
+	 * @param array $arr The array.
+	 * @param callable $callback The callback.
+	 */
+	public function test_array_any( bool $expected, array $arr, callable $callback ) {
+		$this->assertSame( $expected, array_any( $arr, $callback ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public function data_array_any(): array {
+		return array(
+			'empty array' => array(
+				'expected' => false,
+				'arr'      => array(),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'no match'    => array(
+				'expected' => false,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'match'       => array(
+				'expected' => true,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 3 === $value;
+				},
+			),
+			'key match'   => array(
+				'expected' => true,
+				'arr'      => array(
+					'a' => 2,
+					'b' => 3,
+					'c' => 4,
+				),
+				'callback' => function ( $value, $key ) {
+					return 'c' === $key;
+				},
+			),
+		);
+	}
+}

tests/phpunit/tests/compat/arrayFind.php

@@ -0,0 +1,81 @@
+<?php
+
+/**
+ * @group compat
+ *
+ * @covers ::array_find
+ */
+class Tests_Compat_arrayFind extends WP_UnitTestCase {
+
+	/**
+	 * Test that array_find() is always available (either from PHP or WP).
+	 *
+	 * @ticket 62558
+	 */
+	public function test_array_find_availability() {
+		$this->assertTrue( function_exists( 'array_find' ) );
+	}
+
+	/**
+	 * @dataProvider data_array_find
+	 *
+	 * @ticket 62558
+	 *
+	 * @param mixed $expected The expected value.
+	 * @param array $arr      The array.
+	 * @param callable $callback The needle.
+	 */
+	public function test_array_find( $expected, array $arr, callable $callback ) {
+		$this->assertSame( $expected, array_find( $arr, $callback ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public function data_array_find(): array {
+		return array(
+			'empty array'          => array(
+				'expected' => null,
+				'arr'      => array(),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'no match'             => array(
+				'expected' => null,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'match'                => array(
+				'expected' => 3,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 3 === $value;
+				},
+			),
+			'key match'            => array(
+				'expected' => 3,
+				'arr'      => array(
+					'a' => 2,
+					'b' => 3,
+					'c' => 4,
+				),
+				'callback' => function ( $value ) {
+					return 3 === $value;
+				},
+			),
+			'two callback matches' => array(
+				'expected' => 2,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 0 === $value % 2;
+				},
+			),
+
+		);
+	}
+}

tests/phpunit/tests/compat/arrayFindKey.php

@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * @group compat
+ *
+ * @covers ::array_find_key
+ */
+class Test_Compat_arrayFindKey extends WP_UnitTestCase {
+
+	/**
+	 * Test that array_find_key() is always available (either from PHP or WP).
+	 *
+	 * @ticket 62558
+	 */
+	public function test_array_find_key_availability() {
+		$this->assertTrue( function_exists( 'array_find_key' ) );
+	}
+
+	/**
+	 * @dataProvider data_array_find_key
+	 *
+	 * @ticket 62558
+	 *
+	 * @param mixed $expected The expected value.
+	 * @param array $arr The array.
+	 * @param callable $callback The callback.
+	 */
+	public function test_array_find_key( $expected, array $arr, callable $callback ) {
+		$this->assertSame( $expected, array_find_key( $arr, $callback ) );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public function data_array_find_key(): array {
+		return array(
+			'empty array'          => array(
+				'expected' => null,
+				'arr'      => array(),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'no match'             => array(
+				'expected' => null,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 1 === $value;
+				},
+			),
+			'match'                => array(
+				'expected' => 1,
+				'arr'      => array( 2, 3, 4 ),
+				'callback' => function ( $value ) {
+					return 3 === $value;
+				},
+			),
+			'key match'            => array(
+				'expected' => 'b',
+				'arr'      => array(
+					'a' => 2,
+					'b' => 3,
+					'c' => 4,
+				),
+				'callback' => function ( $value ) {
+					return 3 === $value;
+				},
+			),
+			'two callback matches' => array(
+				'expected' => 'b',
+				'arr'      => array(
+					'a' => 2,
+					'b' => 3,
+					'c' => 3,
+				),
+				'callback' => function ( $value ) {
+					return 3 === $value;
+				},
+			),
+		);
+	}
+}