File "Array.php"
Full Path: /home/romayxjt/public_html/wp-content/plugins/the-events-calendar/common/src/Tribe/Utils/Array.php
File size: 22.19 KB
MIME-type: text/x-php
Charset: utf-8
<?php
if ( ! class_exists( 'Tribe__Utils__Array' ) ) {
/**
* Array utilities
*/
class Tribe__Utils__Array {
/**
* Set key/value within an array, can set a key nested inside of a multidimensional array.
*
* Example: set( $a, [ 0, 1, 2 ], 'hi' ) sets $a[0][1][2] = 'hi' and returns $a.
*
* @param mixed $array The array containing the key this sets.
* @param string|array $key To set a key nested multiple levels deep pass an array
* specifying each key in order as a value.
* Example: array( 'lvl1', 'lvl2', 'lvl3' );
* @param mixed $value The value.
*
* @return array Full array with the key set to the specified value.
*/
public static function set( array $array, $key, $value ) {
// Convert strings and such to array.
$key = (array) $key;
// Setup a pointer that we can point to the key specified.
$key_pointer = &$array;
// Iterate through every key, setting the pointer one level deeper each time.
foreach ( $key as $i ) {
// Ensure current array depth can have children set.
if ( ! is_array( $key_pointer ) ) {
// $key_pointer is set but is not an array. Converting it to an array
// would likely lead to unexpected problems for whatever first set it.
$error = sprintf(
'Attempted to set $array[%1$s] but %2$s is already set and is not an array.',
implode( '][', $key ),
$i
);
_doing_it_wrong( __FUNCTION__, esc_html( $error ), '4.3' );
break;
} elseif ( ! isset( $key_pointer[ $i ] ) ) {
$key_pointer[ $i ] = [];
}
// Dive one level deeper into the nested array.
$key_pointer = &$key_pointer[ $i ];
}
// Set the value for the specified key
$key_pointer = $value;
return $array;
}
/**
* Find a value inside of an array or object, including one nested a few levels deep.
*
* Example: get( $a, [ 0, 1, 2 ] ) returns the value of $a[0][1][2] or the default.
*
* @param array $variable Array or object to search within.
* @param array|string $indexes Specify each nested index in order.
* Example: array( 'lvl1', 'lvl2' );
* @param mixed $default Default value if the search finds nothing.
*
* @return mixed The value of the specified index or the default if not found.
*/
public static function get( $variable, $indexes, $default = null ) {
if ( is_object( $variable ) ) {
$variable = (array) $variable;
}
if ( ! is_array( $variable ) ) {
return $default;
}
foreach ( (array) $indexes as $index ) {
if ( ! is_array( $variable ) || ! isset( $variable[ $index ] ) ) {
$variable = $default;
break;
}
$variable = $variable[ $index ];
}
return $variable;
}
/**
* Find a value inside a list of array or objects, including one nested a few levels deep.
*
* @since 4.7.7
*
* Example: get( [$a, $b, $c], [ 0, 1, 2 ] ) returns the value of $a[0][1][2] found in $a, $b or $c
* or the default.
*
* @param array $variables Array of arrays or objects to search within.
* @param array|string $indexes Specify each nested index in order.
* Example: array( 'lvl1', 'lvl2' );
* @param mixed $default Default value if the search finds nothing.
*
* @return mixed The value of the specified index or the default if not found.
*/
public static function get_in_any( array $variables, $indexes, $default = null ) {
foreach ( $variables as $variable ) {
$found = self::get( $variable, $indexes, '__not_found__' );
if ( '__not_found__' !== $found ) {
return $found;
}
}
return $default;
}
/**
* Behaves exactly like the native strpos(), but accepts an array of needles.
*
* @param string $haystack String to search in.
* @param array|string $needles Strings to search for.
* @param int $offset Starting position of search.
*
* @return false|int Integer position of first needle occurrence.
* @see strpos()
*
*/
public static function strpos( $haystack, $needles, $offset = 0 ) {
$needles = (array) $needles;
foreach ( $needles as $i ) {
$search = strpos( $haystack, $i, $offset );
if ( false !== $search ) {
return $search;
}
}
return false;
}
/**
* Converts a list to an array filtering out empty string elements.
*
* @param mixed $value A string representing a list of values separated by the specified separator
* or an array. If the list is a string (e.g. a CSV list) then it will urldecoded
* before processing.
* @param string $sep The char(s) separating the list elements; will be ignored if the list is an array.
*
* @return array An array of list elements.
*/
public static function list_to_array( $value, $sep = ',' ) {
// Let's not jump through all the hoops if the value is empty.
if ( empty( $value ) ) {
return [];
}
// since we might receive URL encoded strings for CSV lists let's URL decode them first
$value = is_array( $value ) ? $value : urldecode( $value );
$sep = is_string( $sep ) ? $sep : ',';
if ( $value === null || $value === '' ) {
return [];
}
if ( ! is_array( $value ) ) {
$value = preg_split( '/\\s*' . preg_quote( $sep ) . '\\s*/', $value );
}
$filtered = [];
foreach ( $value as $v ) {
if ( '' === $v ) {
continue;
}
$filtered[] = is_numeric( $v ) ? $v + 0 : $v;
}
return $filtered;
}
/**
* Returns a list separated by the specified separator.
*
* @since 4.6
*
* @param mixed $list
* @param string $sep
*
* @return string The list separated by the specified separator or the original list if the list is empty.
*/
public static function to_list( $list, $sep = ',' ) {
if ( empty( $list ) ) {
return $list;
}
if ( is_array( $list ) ) {
return implode( $sep, $list );
}
return $list;
}
/**
* Sanitize a multidimensional array.
*
* @since 4.7.18
*
* @param array $data The array to sanitize.
*
* @return array The sanitized array
*
* @link https://gist.github.com/esthezia/5804445
*/
public static function escape_multidimensional_array( $data = [] ) {
if ( ! is_array( $data ) || ! count( $data ) ) {
return [];
}
foreach ( $data as $key => $value ) {
if ( ! is_array( $value ) && ! is_object( $value ) ) {
$data[ $key ] = esc_attr( trim( $value ) );
}
if ( is_array( $value ) ) {
$data[ $key ] = self::escape_multidimensional_array( $value );
}
}
return $data;
}
/**
* Returns an array of values obtained by using the keys on the map; keys
* that do not have a match in map are discarded.
*
* To discriminate from not found results and legitimately `false`
* values from the map the `$found` parameter will be set by reference.
*
* @since 4.7.19
*
* @param string|array $keys One or more keys that should be used to get
* the new values
* @param array $map An associative array relating the keys to the new
* values.
* @param bool $found When using a single key this argument will be
* set to indicate whether the mapping was successful
* or not.
*
* @return array|mixed|false An array of mapped values, a single mapped value when passing
* one key only or `false` if one key was passed but the key could
* not be mapped.
*/
public static function map_or_discard( $keys, array $map, &$found = true ) {
$hash = md5( time() );
$mapped = [];
foreach ( (array) $keys as $key ) {
$meta_key = Tribe__Utils__Array::get( $map, $key, $hash );
if ( $hash === $meta_key ) {
continue;
}
$mapped[] = $meta_key;
}
$found = (bool) count( $mapped );
if ( is_array( $keys ) ) {
return $mapped;
}
return $found ? $mapped[0] : false;
}
/**
* Duplicates any key prefixed with '_' creating an un-prefixed duplicate one.
*
* The un-prefixing and duplication is recursive.
*
* @since 4.9.5
*
* @param mixed $array The array whose keys should be duplicated.
* @param bool $recursive Whether the un-prefixing and duplication should be
* recursive or shallow.
*
* @return array The array with the duplicate, unprefixed, keys or the
* original input if not an array.
*/
public static function add_unprefixed_keys_to( $array, $recursive = false ) {
if ( ! is_array( $array ) ) {
return $array;
}
$unprefixed = [];
foreach ( $array as $key => $value ) {
if ( $recursive && is_array( $value ) ) {
$value = self::add_unprefixed_keys_to( $value, true );
// And also add it to the original array.
$array[ $key ] = array_merge( $array[ $key ], $value );
}
if ( 0 !== strpos( $key, '_' ) ) {
continue;
}
$unprefixed[ substr( $key, 1 ) ] = $value;
}
return array_merge( $array, $unprefixed );
}
/**
* Filters an associative array non-recursively, keeping only the values attached
* to keys starting with the specified prefix.
*
* @since 4.9.5
*
* @param array $array The array to filter.
* @param string $prefix The prefix, or prefixes, of the keys to keep.
*
* @return array The filtered array.
*/
public static function filter_prefixed( array $array, $prefix ) {
$prefixes = implode( '|', array_map( 'preg_quote', (array) $prefix ) );
$pattern = '/^(' . $prefixes . ')/';
$filtered = [];
foreach ( $array as $key => $value ) {
if ( ! preg_match( $pattern, $key ) ) {
continue;
}
$filtered[ $key ] = $value;
}
return $filtered;
}
/**
* Flattens an array transforming each value that is an array and only contains one
* element into that one element.
*
* Typical use case is to flatten arrays like those returned by `get_post_meta( $id )`.
* Empty arrays are replaced with an empty string.
*
* @since 4.9.5
*
* @param array $array The array to flatten.
*
* @return array The flattened array.
*/
public static function flatten( array $array ) {
foreach ( $array as $key => &$value ) {
if ( ! is_array( $value ) ) {
continue;
}
$count = count( $value );
switch ( $count ) {
case 0:
$value = '';
break;
case 1:
$value = reset( $value );
break;
default:
break;
}
}
return $array;
}
/**
* Duplicates any key not prefixed with '_' creating a prefixed duplicate one.
*
* The prefixing and duplication is recursive.
*
* @since 4.9.5
*
* @param mixed $array The array whose keys should be duplicated.
* @param bool $recursive Whether the prefixing and duplication should be
* recursive or shallow.
*
* @return array The array with the duplicate, prefixed, keys or the
* original input if not an array.
*/
public static function add_prefixed_keys_to( $array, $recursive = false ) {
if ( ! is_array( $array ) ) {
return $array;
}
$prefixed = [];
foreach ( $array as $key => $value ) {
if ( $recursive && is_array( $value ) ) {
$value = self::add_prefixed_keys_to( $value, true );
// And also add it to the original array.
$array[ $key ] = array_merge( $array[ $key ], $value );
}
if ( 0 === strpos( $key, '_' ) ) {
continue;
}
$prefixed[ '_' . $key ] = $value;
}
return array_merge( $array, $prefixed );
}
/**
* Recursively key-sort an array.
*
* @since 4.9.5
*
* @param array $array The array to sort, modified by reference.
*
* @return bool The sorting result.
*/
public static function recursive_ksort( array &$array ) {
foreach ( $array as &$value ) {
if ( is_array( $value ) ) {
static::recursive_ksort( $value );
}
}
return ksort( $array );
}
/**
* Returns the value associated with the first index, among the indexes, that is set in the array..
*
* @since 4.9.11
*
* @param array $array The array to search.
* @param array $indexes The indexes to search; in order the function will look from the first to the last.
* @param null $default The value that will be returned if the array does not have any of the indexes set.
*
* @return mixed|null The set value or the default value.
*/
public static function get_first_set( array $array, array $indexes, $default = null ) {
foreach ( $indexes as $index ) {
if ( ! isset( $array[ $index ] ) ) {
continue;
}
return $array[ $index ];
}
return $default;
}
/**
* Discards everything other than array values having string keys and scalar values, ensuring a
* one-dimensional, associative array result.
*
* @link https://www.php.net/manual/language.types.array.php Keys cast to non-strings will be discarded.
*
* @since 4.12.2
*
* @param array $array
*
* @return array Associative or empty array.
*/
public static function filter_to_flat_scalar_associative_array( array $array ) {
$result = [];
if ( ! is_array( $array ) ) {
return $result;
}
foreach ( $array as $k => $v ) {
if ( ! is_string( $k ) ) {
continue;
}
if ( ! is_scalar( $v ) ) {
continue;
}
$result[ $k ] = $v;
}
return $result;
}
/**
* Build an array from migrating aliased key values to their canonical key values, removing all alias keys.
*
* If the original array has values for both the alias and its canonical, keep the canonical's value and
* discard the alias' value.
*
* @since 4.12.2
*
* @param array $original An associative array of values, such as passed shortcode arguments.
* @param array $alias_map An associative array of aliases: key as alias, value as mapped canonical.
* Example: [ 'alias' => 'canonical', 'from' => 'to', 'that' => 'becomes_this' ]
*
* @return array
*/
public static function parse_associative_array_alias( array $original, array $alias_map ) {
// Ensure array values.
$original = (array) $original;
$alias_map = static::filter_to_flat_scalar_associative_array( (array) $alias_map );
// Fail gracefully if alias array wasn't setup as [ 'from' => 'to' ].
if ( empty( $alias_map ) ) {
return $original;
}
$result = $original;
// Parse aliases.
foreach ( $alias_map as $from => $to ) {
// If this alias isn't in use, go onto the next.
if ( ! isset( $result[ $from ] ) ) {
continue;
}
// Only allow setting alias value if canonical value is not already present.
if ( ! isset( $result[ $to ] ) ) {
$result[ $to ] = $result[ $from ];
}
// Always remove the alias key.
unset( $result[ $from ] );
}
return $result;
}
/**
* Stringifies the numeric keys of an array.
*
* @since 4.12.14
*
* @param array<int|string,mixed> $input The input array whose keys should be stringified.
* @param string|null $prefix The prefix that should be use to stringify the keys, if not provided
* then it will be generated.
*
* @return array<string,mixed> The input array with each numeric key stringified.
*/
public static function stringify_keys( array $input, $prefix = null ) {
$prefix = null === $prefix ? uniqid( 'sk_', true ) : $prefix;
$visitor = static function ( $key, $value ) use ( $prefix ) {
$string_key = is_numeric( $key ) ? $prefix . $key : $key;
return [ $string_key, $value ];
};
return static::array_visit_recursive( $input, $visitor );
}
/**
* The inverse of the `stringify_keys` method, it will restore numeric keys for previously
* stringified keys.
*
* @since 4.12.14
*
* @param array<int|string,mixed> $input The input array whose stringified keys should be
* destringified.
* @param string $prefix The prefix that should be used to target only specific string keys.
*
* @return array<int|string,mixed> The input array, its stringified keys destringified.
*/
public static function destringify_keys( array $input, $prefix = 'sk_' ) {
$visitor = static function ( $key, $value ) use ( $prefix ) {
$destringified_key = 0 === self::strpos( $key, $prefix ) ? null : $key;
return [ $destringified_key, $value ];
};
return static::array_visit_recursive( $input, $visitor );
}
/**
* Recursively visits all elements of an array applying the specified callback to each element
* key and value.
*
* @since 4.12.14
*
* @param array $input The input array whose nodes should be visited.
* @param callable $visitor A callback function that will be called on each array item; the callback will
* receive the item key and value as input and should return an array that contains
* the update key and value in the shape `[ <key>, <value> ]`. Returning a `null`
* key will cause the element to be removed from the array.
*/
public static function array_visit_recursive( $input, callable $visitor ) {
if ( ! is_array( $input ) ) {
return $input;
}
$return = [];
foreach ( $input as $key => &$value ) {
if ( is_array( $value ) ) {
$value = static::array_visit_recursive( $value, $visitor );
}
// Ensure visitors can quickly return `null` to remove an element.
list( $updated_key, $update_value ) = array_replace( [ $key, $value ], (array) $visitor( $key, $value ) );
if ( false === $updated_key ) {
// Visitor will be able to remove an element by returning a `false` key for it.
continue;
}
if ( null === $updated_key ) {
// Automatically assign the first available numeric index to the element.
$return[] = $update_value;
} else {
$return[ $updated_key ] = $update_value;
}
}
return $return;
}
/**
* Recursively remove associative, non numeric, keys from an array.
*
* @since 4.12.14
*
* @param array<string|int,mixed> $input The input array.
*
* @return array<int|mixed> An array that only contains integer keys at any of its levels.
*/
public static function remove_numeric_keys_recursive( array $input ) {
return self::array_visit_recursive(
$input,
static function ( $key ) {
return is_numeric( $key ) ? false : $key;
}
);
}
/**
* Recursively remove numeric keys from an array.
*
* @since 4.12.14
*
* @param array<string|int,mixed> $input The input array.
*
* @return array<string,mixed> An array that only contains non numeric keys at any of its levels.
*/
public static function remove_string_keys_recursive( array $input ) {
return self::array_visit_recursive(
$input,
static function ( $key ) {
return !is_numeric( $key ) ? false : $key;
}
);
}
/**
* Merges two or more arrays in the nested format used by WP_Query arguments preserving and merging them correctly.
*
* The method will recursively replace named keys and merge numeric keys. The method takes its name from its intended
* primary use, but it's not limited to query arguments only.
*
* @since 4.12.14
*
* @param array<string|int,mixed> ...$arrays A set of arrays to merge.
*
* @return array<string|int,mixed> The recursively merged array.
*/
public static function merge_recursive_query_vars( array ...$arrays ) {
if ( ! count( $arrays ) ) {
return [];
}
// Temporarily transform numeric keys to string keys generated with time-related randomness.
$stringified = array_map( [ static::class, 'stringify_keys' ], $arrays );
// Replace recursive will recursively replace any entry that has the same string key, stringified keys will never match due to randomness.
$merged = array_replace_recursive( ...$stringified );
// Finally destringify the keys to return something that will resemble, in shape, the original arrays.
return static::destringify_keys( $merged );
}
/**
* Shapes, filtering it, an array to the specified expected set of required keys.
*
* @since 5.0.0
*
* @param array $array The input array to shape.
* @param array $shape The shape to update the array with. It should only define keys
* or arrays of keys. Keys that have no values will be set to `null`.
* To add the key only if set, prefix the key with `?`, e.g. `?foo`.
*
* @return array The input array shaped and ordered per the shape.
*/
public static function shape_filter( array $array, array $shape ): array {
$shaped = [];
foreach ( $shape as $shape_index => $shape_key ) {
$optional = is_array( $shape_key ) ?
strpos( $shape_index, '?' ) === 0
: strpos( $shape_key, '?' ) === 0;
if ( is_array( $shape_key ) ) {
$shape_index = $optional ? substr( $shape_index, 1 ) : $shape_index;
if ( $optional && ! isset( $array[ $shape_index ] ) ) {
continue;
}
$shaped[ $shape_index ] = self::shape_filter( $array[$shape_index] ?? [], $shape_key );
} else {
$shape_key = $optional ? substr( $shape_key, 1 ) : $shape_key;
if ( ! isset( $array[ $shape_key ] ) && $optional ) {
continue;
}
$shaped[ $shape_key ] = $array[ $shape_key ] ?? null;
}
}
return $shaped;
}
/**
* Searches an array using a callback and returns the index of the first match.
*
* This method fills the gap left by the non-existence of an `array_usearch` function.
*
* @since 5.0.0
*
* @param mixed $needle The element to search in the array.
* @param array $haystack The array to search.
* @param callable $callback A callback function with signature `fn($needle, $value, $key) :bool`
* that will be used to find the first match of needle in haystack.
*
* @return string|int|false Either the index of the first match or `false` if no match was found.
*/
public static function usearch( $needle, array $haystack, callable $callback ) {
foreach ( $haystack as $key => $value ) {
if ( $callback( $needle, $value, $key ) ) {
return $key;
}
}
return false;
}
}
}