/** * WordPress List utility class * * @package WordPress * @since 4.7.0 */ /** * List utility. * * Utility class to handle operations on an array of objects. * * @since 4.7.0 */ class WP_List_Util { /** * The input array. * * @since 4.7.0 * @access private * @var array */ private $input = array(); /** * The output array. * * @since 4.7.0 * @access private * @var array */ private $output = array(); /** * Temporary arguments for sorting. * * @since 4.7.0 * @access private * @var array */ private $orderby = array(); /** * Constructor. * * Sets the input array. * * @since 4.7.0 * * @param array $input Array to perform operations on. */ public function __construct( $input ) { $this->output = $this->input = $input; } /** * Returns the original input array. * * @since 4.7.0 * @access public * * @return array The input array. */ public function get_input() { return $this->input; } /** * Returns the output array. * * @since 4.7.0 * @access public * * @return array The output array. */ public function get_output() { return $this->output; } /** * Filters the list, based on a set of key => value arguments. * * @since 4.7.0 * * @param array $args Optional. An array of key => value arguments to match * against each object. Default empty array. * @param string $operator Optional. The logical operation to perform. 'AND' means * all elements from the array must match. 'OR' means only * one element needs to match. 'NOT' means no elements may * match. Default 'AND'. * @return array Array of found values. */ public function filter( $args = array(), $operator = 'AND' ) { if ( empty( $args ) ) { return $this->output; } $operator = strtoupper( $operator ); if ( ! in_array( $operator, array( 'AND', 'OR', 'NOT' ), true ) ) { return array(); } $count = count( $args ); $filtered = array(); foreach ( $this->output as $key => $obj ) { $to_match = (array) $obj; $matched = 0; foreach ( $args as $m_key => $m_value ) { if ( array_key_exists( $m_key, $to_match ) && $m_value == $to_match[ $m_key ] ) { $matched++; } } if ( ( 'AND' == $operator && $matched == $count ) || ( 'OR' == $operator && $matched > 0 ) || ( 'NOT' == $operator && 0 == $matched ) ) { $filtered[$key] = $obj; } } $this->output = $filtered; return $this->output; } /** * Plucks a certain field out of each object in the list. * * This has the same functionality and prototype of * array_column() (PHP 5.5) but also supports objects. * * @since 4.7.0 * * @param int|string $field Field from the object to place instead of the entire object * @param int|string $index_key Optional. Field from the object to use as keys for the new array. * Default null. * @return array Array of found values. If `$index_key` is set, an array of found values with keys * corresponding to `$index_key`. If `$index_key` is null, array keys from the original * `$list` will be preserved in the results. */ public function pluck( $field, $index_key = null ) { if ( ! $index_key ) { /* * This is simple. Could at some point wrap array_column() * if we knew we had an array of arrays. */ foreach ( $this->output as $key => $value ) { if ( is_object( $value ) ) { $this->output[ $key ] = $value->$field; } else { $this->output[ $key ] = $value[ $field ]; } } return $this->output; } /* * When index_key is not set for a particular item, push the value * to the end of the stack. This is how array_column() behaves. */ $newlist = array(); foreach ( $this->output as $value ) { if ( is_object( $value ) ) { if ( isset( $value->$index_key ) ) { $newlist[ $value->$index_key ] = $value->$field; } else { $newlist[] = $value->$field; } } else { if ( isset( $value[ $index_key ] ) ) { $newlist[ $value[ $index_key ] ] = $value[ $field ]; } else { $newlist[] = $value[ $field ]; } } } $this->output = $newlist; return $this->output; } /** * Sorts the list, based on one or more orderby arguments. * * @since 4.7.0 * * @param string|array $orderby Optional. Either the field name to order by or an array * of multiple orderby fields as $orderby => $order. * @param string $order Optional. Either 'ASC' or 'DESC'. Only used if $orderby * is a string. * @param bool $preserve_keys Optional. Whether to preserve keys. Default false. * @return array The sorted array. */ public function sort( $orderby = array(), $order = 'ASC', $preserve_keys = false ) { if ( empty( $orderby ) ) { return $this->output; } if ( is_string( $orderby ) ) { $orderby = array( $orderby => $order ); } foreach ( $orderby as $field => $direction ) { $orderby[ $field ] = 'DESC' === strtoupper( $direction ) ? 'DESC' : 'ASC'; } $this->orderby = $orderby; if ( $preserve_keys ) { uasort( $this->output, array( $this, 'sort_callback' ) ); } else { usort( $this->output, array( $this, 'sort_callback' ) ); } $this->orderby = array(); return $this->output; } /** * Callback to sort the list by specific fields. * * @since 4.7.0 * @access private * * @see WP_List_Util::sort() * * @param object|array $a One object to compare. * @param object|array $b The other object to compare. * @return int 0 if both objects equal. -1 if second object should come first, 1 otherwise. */ private function sort_callback( $a, $b ) { if ( empty( $this->orderby ) ) { return 0; } $a = (array) $a; $b = (array) $b; foreach ( $this->orderby as $field => $direction ) { if ( ! isset( $a[ $field ] ) || ! isset( $b[ $field ] ) ) { continue; } if ( $a[ $field ] == $b[ $field ] ) { continue; } $results = 'DESC' === $direction ? array( 1, -1 ) : array( -1, 1 ); if ( is_numeric( $a[ $field ] ) && is_numeric( $b[ $field ] ) ) { return ( $a[ $field ] < $b[ $field ] ) ? $results[0] : $results[1]; } return 0 > strcmp( $a[ $field ], $b[ $field ] ) ? $results[0] : $results[1]; } return 0; } }