WP_List_Util

List utility.

Defined (1)

The class is defined in the following location(s).

/wp-includes/class-wp-list-util.php  
  1. class WP_List_Util { 
  2. /** 
  3. * The input array. 
  4. * @since 4.7.0 
  5. * @access private 
  6. * @var array 
  7. */ 
  8. private $input = array(); 
  9.  
  10. /** 
  11. * The output array. 
  12. * @since 4.7.0 
  13. * @access private 
  14. * @var array 
  15. */ 
  16. private $output = array(); 
  17.  
  18. /** 
  19. * Temporary arguments for sorting. 
  20. * @since 4.7.0 
  21. * @access private 
  22. * @var array 
  23. */ 
  24. private $orderby = array(); 
  25.  
  26. /** 
  27. * Constructor. 
  28. * Sets the input array. 
  29. * @since 4.7.0 
  30. * @param array $input Array to perform operations on. 
  31. */ 
  32. public function __construct( $input ) { 
  33. $this->output = $this->input = $input; 
  34.  
  35. /** 
  36. * Returns the original input array. 
  37. * @since 4.7.0 
  38. * @access public 
  39. * @return array The input array. 
  40. */ 
  41. public function get_input() { 
  42. return $this->input; 
  43.  
  44. /** 
  45. * Returns the output array. 
  46. * @since 4.7.0 
  47. * @access public 
  48. * @return array The output array. 
  49. */ 
  50. public function get_output() { 
  51. return $this->output; 
  52.  
  53. /** 
  54. * Filters the list, based on a set of key => value arguments. 
  55. * @since 4.7.0 
  56. * @param array $args Optional. An array of key => value arguments to match 
  57. * against each object. Default empty array. 
  58. * @param string $operator Optional. The logical operation to perform. 'AND' means 
  59. * all elements from the array must match. 'OR' means only 
  60. * one element needs to match. 'NOT' means no elements may 
  61. * match. Default 'AND'. 
  62. * @return array Array of found values. 
  63. */ 
  64. public function filter( $args = array(), $operator = 'AND' ) { 
  65. if ( empty( $args ) ) { 
  66. return $this->output; 
  67.  
  68. $operator = strtoupper( $operator ); 
  69.  
  70. if ( ! in_array( $operator, array( 'AND', 'OR', 'NOT' ), true ) ) { 
  71. return array(); 
  72.  
  73. $count = count( $args ); 
  74. $filtered = array(); 
  75.  
  76. foreach ( $this->output as $key => $obj ) { 
  77. $to_match = (array) $obj; 
  78.  
  79. $matched = 0; 
  80. foreach ( $args as $m_key => $m_value ) { 
  81. if ( array_key_exists( $m_key, $to_match ) && $m_value == $to_match[ $m_key ] ) { 
  82. $matched++; 
  83.  
  84. if ( 
  85. ( 'AND' == $operator && $matched == $count ) || 
  86. ( 'OR' == $operator && $matched > 0 ) || 
  87. ( 'NOT' == $operator && 0 == $matched ) 
  88. ) { 
  89. $filtered[$key] = $obj; 
  90.  
  91. $this->output = $filtered; 
  92.  
  93. return $this->output; 
  94.  
  95. /** 
  96. * Plucks a certain field out of each object in the list. 
  97. * This has the same functionality and prototype of 
  98. * array_column() (PHP 5.5) but also supports objects. 
  99. * @since 4.7.0 
  100. * @param int|string $field Field from the object to place instead of the entire object 
  101. * @param int|string $index_key Optional. Field from the object to use as keys for the new array. 
  102. * Default null. 
  103. * @return array Array of found values. If `$index_key` is set, an array of found values with keys 
  104. * corresponding to `$index_key`. If `$index_key` is null, array keys from the original 
  105. * `$list` will be preserved in the results. 
  106. */ 
  107. public function pluck( $field, $index_key = null ) { 
  108. if ( ! $index_key ) { 
  109. /** 
  110. * This is simple. Could at some point wrap array_column() 
  111. * if we knew we had an array of arrays. 
  112. */ 
  113. foreach ( $this->output as $key => $value ) { 
  114. if ( is_object( $value ) ) { 
  115. $this->output[ $key ] = $value->$field; 
  116. } else { 
  117. $this->output[ $key ] = $value[ $field ]; 
  118. return $this->output; 
  119.  
  120. /** 
  121. * When index_key is not set for a particular item, push the value 
  122. * to the end of the stack. This is how array_column() behaves. 
  123. */ 
  124. $newlist = array(); 
  125. foreach ( $this->output as $value ) { 
  126. if ( is_object( $value ) ) { 
  127. if ( isset( $value->$index_key ) ) { 
  128. $newlist[ $value->$index_key ] = $value->$field; 
  129. } else { 
  130. $newlist[] = $value->$field; 
  131. } else { 
  132. if ( isset( $value[ $index_key ] ) ) { 
  133. $newlist[ $value[ $index_key ] ] = $value[ $field ]; 
  134. } else { 
  135. $newlist[] = $value[ $field ]; 
  136.  
  137. $this->output = $newlist; 
  138.  
  139. return $this->output; 
  140.  
  141. /** 
  142. * Sorts the list, based on one or more orderby arguments. 
  143. * @since 4.7.0 
  144. * @param string|array $orderby Optional. Either the field name to order by or an array 
  145. * of multiple orderby fields as $orderby => $order. 
  146. * @param string $order Optional. Either 'ASC' or 'DESC'. Only used if $orderby 
  147. * is a string. 
  148. * @param bool $preserve_keys Optional. Whether to preserve keys. Default false. 
  149. * @return array The sorted array. 
  150. */ 
  151. public function sort( $orderby = array(), $order = 'ASC', $preserve_keys = false ) { 
  152. if ( empty( $orderby ) ) { 
  153. return $this->output; 
  154.  
  155. if ( is_string( $orderby ) ) { 
  156. $orderby = array( $orderby => $order ); 
  157.  
  158. foreach ( $orderby as $field => $direction ) { 
  159. $orderby[ $field ] = 'DESC' === strtoupper( $direction ) ? 'DESC' : 'ASC'; 
  160.  
  161. $this->orderby = $orderby; 
  162.  
  163. if ( $preserve_keys ) { 
  164. uasort( $this->output, array( $this, 'sort_callback' ) ); 
  165. } else { 
  166. usort( $this->output, array( $this, 'sort_callback' ) ); 
  167.  
  168. $this->orderby = array(); 
  169.  
  170. return $this->output; 
  171.  
  172. /** 
  173. * Callback to sort the list by specific fields. 
  174. * @since 4.7.0 
  175. * @access private 
  176. * @see WP_List_Util::sort() 
  177. * @param object|array $a One object to compare. 
  178. * @param object|array $b The other object to compare. 
  179. * @return int 0 if both objects equal. -1 if second object should come first, 1 otherwise. 
  180. */ 
  181. private function sort_callback( $a, $b ) { 
  182. if ( empty( $this->orderby ) ) { 
  183. return 0; 
  184.  
  185. $a = (array) $a; 
  186. $b = (array) $b; 
  187.  
  188. foreach ( $this->orderby as $field => $direction ) { 
  189. if ( ! isset( $a[ $field ] ) || ! isset( $b[ $field ] ) ) { 
  190. continue; 
  191.  
  192. if ( $a[ $field ] == $b[ $field ] ) { 
  193. continue; 
  194.  
  195. $results = 'DESC' === $direction ? array( 1, -1 ) : array( -1, 1 ); 
  196.  
  197. if ( is_numeric( $a[ $field ] ) && is_numeric( $b[ $field ] ) ) { 
  198. return ( $a[ $field ] < $b[ $field ] ) ? $results[0] : $results[1]; 
  199.  
  200. return 0 > strcmp( $a[ $field ], $b[ $field ] ) ? $results[0] : $results[1]; 
  201.  
  202. return 0;