diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index 3c7e204db33e4..0c6f44591f6ed 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -4626,6 +4626,65 @@ function _wp_array_get( $array, $path, $default = null ) { return $array; } +/** + * Sets an array in depth based on a path of keys. + * + * It is the PHP equivalent of JavaScript's `lodash.set()` and mirroring it may help other components + * retain some symmetry between client and server implementations. + * + * Example usage: + * + * $array = array(); + * _wp_array_set( $array, array( 'a', 'b', 'c', 1 ); + * $array becomes: + * array( + * 'a' => array( + * 'b' => array( + * 'c' => 1, + * ), + * ), + * ); + * + * @param array $array An array that we want to mutate to include a specific value in a path. + * @param array $path An array of keys describing the path that we want to mutate. + * @param mixed $value The value that will be set. + */ +function _wp_array_set( &$array, $path, $value = null ) { + // Confirm $array is valid. + if ( ! is_array( $array ) ) { + return; + } + + // Confirm $path is valid. + if ( ! is_array( $path ) ) { + return; + } + $path_length = count( $path ); + if ( 0 === $path_length ) { + return; + } + foreach ( $path as $path_element ) { + if ( + ! is_string( $path_element ) && ! is_integer( $path_element ) && + ! is_null( $path_element ) + ) { + return; + } + } + + for ( $i = 0; $i < $path_length - 1; ++$i ) { + $path_element = $path[ $i ]; + if ( + ! array_key_exists( $path_element, $array ) || + ! is_array( $array[ $path_element ] ) + ) { + $array[ $path_element ] = array(); + } + $array = &$array[ $path_element ]; // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.VariableRedeclaration + } + $array[ $path[ $i ] ] = $value; +} + /** * Determines if the variable is a numeric-indexed array. * diff --git a/tests/phpunit/tests/class-wp-array-set-test.php b/tests/phpunit/tests/class-wp-array-set-test.php new file mode 100644 index 0000000000000..9accb2deae06f --- /dev/null +++ b/tests/phpunit/tests/class-wp-array-set-test.php @@ -0,0 +1,130 @@ +assertSame( + $test_array, + array( 'a' => 1 ) + ); + + $test_array = array( 'a' => 2 ); + _wp_array_set( $test_array, array( 'a' ), 3 ); + $this->assertSame( + $test_array, + array( 'a' => 3 ) + ); + + $test_array = array( 'b' => 1 ); + _wp_array_set( $test_array, array( 'a' ), 3 ); + $this->assertSame( + $test_array, + array( + 'b' => 1, + 'a' => 3, + ) + ); + } + + /** + * Test _wp_array_set() with subtree paths. + */ + public function test_subtree_set() { + $test_array = array(); + _wp_array_set( $test_array, array( 'a', 'b', 'c' ), 1 ); + $this->assertSame( + $test_array, + array( 'a' => array( 'b' => array( 'c' => 1 ) ) ) + ); + + $test_array = array( 'b' => 3 ); + _wp_array_set( $test_array, array( 'a', 'b', 'c' ), 1 ); + $this->assertSame( + $test_array, + array( + 'b' => 3, + 'a' => array( 'b' => array( 'c' => 1 ) ), + ) + ); + + $test_array = array( + 'b' => 3, + 'a' => 1, + ); + _wp_array_set( $test_array, array( 'a', 'b', 'c' ), 1 ); + $this->assertSame( + $test_array, + array( + 'b' => 3, + 'a' => array( 'b' => array( 'c' => 1 ) ), + ) + ); + + $test_array = array( + 'b' => 3, + 'a' => array(), + ); + _wp_array_set( $test_array, array( 'a', 'b', 'c' ), 1 ); + $this->assertSame( + $test_array, + array( + 'b' => 3, + 'a' => array( 'b' => array( 'c' => 1 ) ), + ) + ); + } + + /** + * Test _wp_array_set() with invalid parameters. + */ + public function test_invalid_parameters_set() { + $test = 3; + _wp_array_set( $test, array( 'a' ), 1 ); + $this->assertSame( + $test, + 3 + ); + + $test_array = array( 'a' => 2 ); + _wp_array_set( $test_array, 'a', 3 ); + $this->assertSame( + $test_array, + array( 'a' => 2 ) + ); + + $test_array = array( 'a' => 2 ); + _wp_array_set( $test_array, null, 3 ); + $this->assertSame( + $test_array, + array( 'a' => 2 ) + ); + + $test_array = array( 'a' => 2 ); + _wp_array_set( $test_array, array(), 3 ); + $this->assertSame( + $test_array, + array( 'a' => 2 ) + ); + + $test_array = array( 'a' => 2 ); + _wp_array_set( $test_array, array( 'a', array() ), 3 ); + $this->assertSame( + $test_array, + array( 'a' => 2 ) + ); + } +}