| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * WordPress List utility class 4 * 5 * @package WordPress 6 * @since 4.7.0 7 */ 8 9 /** 10 * List utility. 11 * 12 * Utility class to handle operations on an array of objects or arrays. 13 * 14 * @since 4.7.0 15 */ 16 #[AllowDynamicProperties] 17 class WP_List_Util { 18 /** 19 * The input array. 20 * 21 * @since 4.7.0 22 * @var array 23 */ 24 private $input = array(); 25 26 /** 27 * The output array. 28 * 29 * @since 4.7.0 30 * @var array 31 */ 32 private $output = array(); 33 34 /** 35 * Temporary arguments for sorting. 36 * 37 * @since 4.7.0 38 * @var string[] 39 */ 40 private $orderby = array(); 41 42 /** 43 * Constructor. 44 * 45 * Sets the input array. 46 * 47 * @since 4.7.0 48 * 49 * @param array $input Array to perform operations on. 50 */ 51 public function __construct( $input ) { 52 $this->output = $input; 53 $this->input = $input; 54 } 55 56 /** 57 * Returns the original input array. 58 * 59 * @since 4.7.0 60 * 61 * @return array The input array. 62 */ 63 public function get_input() { 64 return $this->input; 65 } 66 67 /** 68 * Returns the output array. 69 * 70 * @since 4.7.0 71 * 72 * @return array The output array. 73 */ 74 public function get_output() { 75 return $this->output; 76 } 77 78 /** 79 * Filters the list, based on a set of key => value arguments. 80 * 81 * Retrieves the objects from the list that match the given arguments. 82 * Key represents property name, and value represents property value. 83 * 84 * If an object has more properties than those specified in arguments, 85 * that will not disqualify it. When using the 'and' operator, 86 * any missing properties will disqualify it. 87 * 88 * @since 4.7.0 89 * 90 * @param array $args Optional. An array of key => value arguments to match 91 * against each object. Default empty array. 92 * @param string $operator Optional. The logical operation to perform. 'and' means 93 * all elements from the array must match. 'or' means only 94 * one element needs to match. 'not' means no elements may 95 * match. The value is case-insensitive. Default 'and'. 96 * @return array Array of found values. 97 * 98 * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator 99 */ 100 public function filter( $args = array(), $operator = 'and' ) { 101 if ( empty( $args ) ) { 102 return $this->output; 103 } 104 105 $operator = strtoupper( $operator ); 106 107 if ( ! in_array( $operator, array( 'AND', 'OR', 'NOT' ), true ) ) { 108 $this->output = array(); 109 return $this->output; 110 } 111 112 $count = count( $args ); 113 $filtered = array(); 114 115 foreach ( $this->output as $key => $obj ) { 116 $matched = 0; 117 118 foreach ( $args as $m_key => $m_value ) { 119 if ( is_array( $obj ) ) { 120 // Treat object as an array. 121 if ( array_key_exists( $m_key, $obj ) && ( $m_value == $obj[ $m_key ] ) ) { 122 ++$matched; 123 } 124 } elseif ( is_object( $obj ) ) { 125 // Treat object as an object. 126 if ( isset( $obj->{$m_key} ) && ( $m_value == $obj->{$m_key} ) ) { 127 ++$matched; 128 } 129 } 130 } 131 132 if ( ( 'AND' === $operator && $matched === $count ) 133 || ( 'OR' === $operator && $matched > 0 ) 134 || ( 'NOT' === $operator && 0 === $matched ) 135 ) { 136 $filtered[ $key ] = $obj; 137 } 138 } 139 140 $this->output = $filtered; 141 142 return $this->output; 143 } 144 145 /** 146 * Plucks a certain field out of each element in the input array. 147 * 148 * This has the same functionality and prototype of 149 * array_column() (PHP 5.5) but also supports objects. 150 * 151 * @since 4.7.0 152 * 153 * @param int|string $field Field to fetch from the object or array. 154 * @param int|string $index_key Optional. Field from the element to use as keys for the new array. 155 * Default null. 156 * @return array Array of found values. If `$index_key` is set, an array of found values with keys 157 * corresponding to `$index_key`. If `$index_key` is null, array keys from the original 158 * `$list` will be preserved in the results. 159 */ 160 public function pluck( $field, $index_key = null ) { 161 $newlist = array(); 162 163 if ( ! $index_key ) { 164 /* 165 * This is simple. Could at some point wrap array_column() 166 * if we knew we had an array of arrays. 167 */ 168 foreach ( $this->output as $key => $value ) { 169 if ( is_object( $value ) ) { 170 $newlist[ $key ] = $value->$field; 171 } elseif ( is_array( $value ) ) { 172 $newlist[ $key ] = $value[ $field ]; 173 } else { 174 _doing_it_wrong( 175 __METHOD__, 176 __( 'Values for the input array must be either objects or arrays.' ), 177 '6.2.0' 178 ); 179 } 180 } 181 182 $this->output = $newlist; 183 184 return $this->output; 185 } 186 187 /* 188 * When index_key is not set for a particular item, push the value 189 * to the end of the stack. This is how array_column() behaves. 190 */ 191 foreach ( $this->output as $value ) { 192 if ( is_object( $value ) ) { 193 if ( isset( $value->$index_key ) ) { 194 $newlist[ $value->$index_key ] = $value->$field; 195 } else { 196 $newlist[] = $value->$field; 197 } 198 } elseif ( is_array( $value ) ) { 199 if ( isset( $value[ $index_key ] ) ) { 200 $newlist[ $value[ $index_key ] ] = $value[ $field ]; 201 } else { 202 $newlist[] = $value[ $field ]; 203 } 204 } else { 205 _doing_it_wrong( 206 __METHOD__, 207 __( 'Values for the input array must be either objects or arrays.' ), 208 '6.2.0' 209 ); 210 } 211 } 212 213 $this->output = $newlist; 214 215 return $this->output; 216 } 217 218 /** 219 * Sorts the input array based on one or more orderby arguments. 220 * 221 * @since 4.7.0 222 * 223 * @param string|array $orderby Optional. Either the field name to order by or an array 224 * of multiple orderby fields as `$orderby => $order`. 225 * Default empty array. 226 * @param string $order Optional. Either 'ASC' or 'DESC'. Only used if `$orderby` 227 * is a string. Default 'ASC'. 228 * @param bool $preserve_keys Optional. Whether to preserve keys. Default false. 229 * @return array The sorted array. 230 */ 231 public function sort( $orderby = array(), $order = 'ASC', $preserve_keys = false ) { 232 if ( empty( $orderby ) ) { 233 return $this->output; 234 } 235 236 if ( is_string( $orderby ) ) { 237 $orderby = array( $orderby => $order ); 238 } 239 240 foreach ( $orderby as $field => $direction ) { 241 $orderby[ $field ] = 'DESC' === strtoupper( $direction ) ? 'DESC' : 'ASC'; 242 } 243 244 $this->orderby = $orderby; 245 246 if ( $preserve_keys ) { 247 uasort( $this->output, array( $this, 'sort_callback' ) ); 248 } else { 249 usort( $this->output, array( $this, 'sort_callback' ) ); 250 } 251 252 $this->orderby = array(); 253 254 return $this->output; 255 } 256 257 /** 258 * Callback to sort an array by specific fields. 259 * 260 * @since 4.7.0 261 * 262 * @see WP_List_Util::sort() 263 * 264 * @param object|array $a One object to compare. 265 * @param object|array $b The other object to compare. 266 * @return int 0 if both objects equal. -1 if second object should come first, 1 otherwise. 267 */ 268 private function sort_callback( $a, $b ) { 269 if ( empty( $this->orderby ) ) { 270 return 0; 271 } 272 273 $a = (array) $a; 274 $b = (array) $b; 275 276 foreach ( $this->orderby as $field => $direction ) { 277 if ( ! isset( $a[ $field ] ) || ! isset( $b[ $field ] ) ) { 278 continue; 279 } 280 281 if ( $a[ $field ] == $b[ $field ] ) { 282 continue; 283 } 284 285 $results = 'DESC' === $direction ? array( 1, -1 ) : array( -1, 1 ); 286 287 if ( is_numeric( $a[ $field ] ) && is_numeric( $b[ $field ] ) ) { 288 return ( $a[ $field ] < $b[ $field ] ) ? $results[0] : $results[1]; 289 } 290 291 return 0 > strcmp( $a[ $field ], $b[ $field ] ) ? $results[0] : $results[1]; 292 } 293 294 return 0; 295 } 296 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Tue Nov 17 08:20:01 2026 | Cross-referenced by PHPXref |