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]
17class 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. Default 'AND'.
96 * @return array Array of found values.
97 */
98 public function filter( $args = array(), $operator = 'AND' ) {
99 if ( empty( $args ) ) {
100 return $this->output;
101 }
102
103 $operator = strtoupper( $operator );
104
105 if ( ! in_array( $operator, array( 'AND', 'OR', 'NOT' ), true ) ) {
106 $this->output = array();
107 return $this->output;
108 }
109
110 $count = count( $args );
111 $filtered = array();
112
113 foreach ( $this->output as $key => $obj ) {
114 $matched = 0;
115
116 foreach ( $args as $m_key => $m_value ) {
117 if ( is_array( $obj ) ) {
118 // Treat object as an array.
119 if ( array_key_exists( $m_key, $obj ) && ( $m_value == $obj[ $m_key ] ) ) {
120 ++$matched;
121 }
122 } elseif ( is_object( $obj ) ) {
123 // Treat object as an object.
124 if ( isset( $obj->{$m_key} ) && ( $m_value == $obj->{$m_key} ) ) {
125 ++$matched;
126 }
127 }
128 }
129
130 if ( ( 'AND' === $operator && $matched === $count )
131 || ( 'OR' === $operator && $matched > 0 )
132 || ( 'NOT' === $operator && 0 === $matched )
133 ) {
134 $filtered[ $key ] = $obj;
135 }
136 }
137
138 $this->output = $filtered;
139
140 return $this->output;
141 }
142
143 /**
144 * Plucks a certain field out of each element in the input array.
145 *
146 * This has the same functionality and prototype of
147 * array_column() (PHP 5.5) but also supports objects.
148 *
149 * @since 4.7.0
150 *
151 * @param int|string $field Field to fetch from the object or array.
152 * @param int|string $index_key Optional. Field from the element to use as keys for the new array.
153 * Default null.
154 * @return array Array of found values. If `$index_key` is set, an array of found values with keys
155 * corresponding to `$index_key`. If `$index_key` is null, array keys from the original
156 * `$list` will be preserved in the results.
157 */
158 public function pluck( $field, $index_key = null ) {
159 $newlist = array();
160
161 if ( ! $index_key ) {
162 /*
163 * This is simple. Could at some point wrap array_column()
164 * if we knew we had an array of arrays.
165 */
166 foreach ( $this->output as $key => $value ) {
167 if ( is_object( $value ) ) {
168 $newlist[ $key ] = $value->$field;
169 } elseif ( is_array( $value ) ) {
170 $newlist[ $key ] = $value[ $field ];
171 } else {
172 _doing_it_wrong(
173 __METHOD__,
174 __( 'Values for the input array must be either objects or arrays.' ),
175 '6.2.0'
176 );
177 }
178 }
179
180 $this->output = $newlist;
181
182 return $this->output;
183 }
184
185 /*
186 * When index_key is not set for a particular item, push the value
187 * to the end of the stack. This is how array_column() behaves.
188 */
189 foreach ( $this->output as $value ) {
190 if ( is_object( $value ) ) {
191 if ( isset( $value->$index_key ) ) {
192 $newlist[ $value->$index_key ] = $value->$field;
193 } else {
194 $newlist[] = $value->$field;
195 }
196 } elseif ( is_array( $value ) ) {
197 if ( isset( $value[ $index_key ] ) ) {
198 $newlist[ $value[ $index_key ] ] = $value[ $field ];
199 } else {
200 $newlist[] = $value[ $field ];
201 }
202 } else {
203 _doing_it_wrong(
204 __METHOD__,
205 __( 'Values for the input array must be either objects or arrays.' ),
206 '6.2.0'
207 );
208 }
209 }
210
211 $this->output = $newlist;
212
213 return $this->output;
214 }
215
216 /**
217 * Sorts the input array based on one or more orderby arguments.
218 *
219 * @since 4.7.0
220 *
221 * @param string|array $orderby Optional. Either the field name to order by or an array
222 * of multiple orderby fields as `$orderby => $order`.
223 * Default empty array.
224 * @param string $order Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
225 * is a string. Default 'ASC'.
226 * @param bool $preserve_keys Optional. Whether to preserve keys. Default false.
227 * @return array The sorted array.
228 */
229 public function sort( $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
230 if ( empty( $orderby ) ) {
231 return $this->output;
232 }
233
234 if ( is_string( $orderby ) ) {
235 $orderby = array( $orderby => $order );
236 }
237
238 foreach ( $orderby as $field => $direction ) {
239 $orderby[ $field ] = 'DESC' === strtoupper( $direction ) ? 'DESC' : 'ASC';
240 }
241
242 $this->orderby = $orderby;
243
244 if ( $preserve_keys ) {
245 uasort( $this->output, array( $this, 'sort_callback' ) );
246 } else {
247 usort( $this->output, array( $this, 'sort_callback' ) );
248 }
249
250 $this->orderby = array();
251
252 return $this->output;
253 }
254
255 /**
256 * Callback to sort an array by specific fields.
257 *
258 * @since 4.7.0
259 *
260 * @see WP_List_Util::sort()
261 *
262 * @param object|array $a One object to compare.
263 * @param object|array $b The other object to compare.
264 * @return int 0 if both objects equal. -1 if second object should come first, 1 otherwise.
265 */
266 private function sort_callback( $a, $b ) {
267 if ( empty( $this->orderby ) ) {
268 return 0;
269 }
270
271 $a = (array) $a;
272 $b = (array) $b;
273
274 foreach ( $this->orderby as $field => $direction ) {
275 if ( ! isset( $a[ $field ] ) || ! isset( $b[ $field ] ) ) {
276 continue;
277 }
278
279 if ( $a[ $field ] == $b[ $field ] ) {
280 continue;
281 }
282
283 $results = 'DESC' === $direction ? array( 1, -1 ) : array( -1, 1 );
284
285 if ( is_numeric( $a[ $field ] ) && is_numeric( $b[ $field ] ) ) {
286 return ( $a[ $field ] < $b[ $field ] ) ? $results[0] : $results[1];
287 }
288
289 return 0 > strcmp( $a[ $field ], $b[ $field ] ) ? $results[0] : $results[1];
290 }
291
292 return 0;
293 }
294}
295