Complex classes like Collection often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use Collection, and based on these observations, apply Extract Interface, too.
1 | <?php |
||
50 | class Collection implements Countable, ArrayAccess |
||
51 | { |
||
52 | /** |
||
53 | * Constants used as comparison operators in where() method |
||
54 | */ |
||
55 | |||
56 | /** Use this operator constant to test for identity (exact same) **/ |
||
57 | const WHERE_ID = '==='; |
||
58 | |||
59 | /** Use this operator constant to test for non-identity **/ |
||
60 | const WHERE_NID = '!=='; |
||
61 | |||
62 | /** Use this operator constant to test for equality **/ |
||
63 | const WHERE_EQ = '=='; |
||
64 | |||
65 | /** Use this operator constant to test for non-equality **/ |
||
66 | const WHERE_NEQ = '!='; |
||
67 | |||
68 | /** Use this operator constant to test for less-than **/ |
||
69 | const WHERE_LT = '<'; |
||
70 | |||
71 | /** Use this operator constant to test for greater-than or equal-to **/ |
||
72 | const WHERE_LTE = '<='; |
||
73 | |||
74 | /** Use this operator constant to test for greater-than **/ |
||
75 | const WHERE_GT = '>'; |
||
76 | |||
77 | /** Use this operator constant to test for greater-than or equal-to **/ |
||
78 | const WHERE_GTE = '>='; |
||
79 | |||
80 | /** Use this operator constant to test for case insensitive equality **/ |
||
81 | const WHERE_LIKE = 'like'; |
||
82 | |||
83 | /** Use this operator constant to test for case instensitiv inequality **/ |
||
84 | const WHERE_NLIKE = '!like'; |
||
85 | |||
86 | /** Use this operator constant to test for descendants or instances of a class **/ |
||
87 | const WHERE_ISA = 'instanceof'; |
||
88 | |||
89 | /** Use this operator constant to test for values that aren't descendants or instances of a class **/ |
||
90 | const WHERE_NISA = '!instanceof'; |
||
91 | |||
92 | /** Use this operator constant to test for internal PHP types **/ |
||
93 | const WHERE_TOF = 'typeof'; |
||
94 | |||
95 | /** Use this operator constant to test for internal PHP type (negated) **/ |
||
96 | const WHERE_NTOF = '!typeof'; |
||
97 | |||
98 | /** Use this operator constant to test against a regex pattern **/ |
||
99 | const WHERE_MATCH = 'match'; |
||
100 | |||
101 | /** Use this operator constant to test against a regex pattern (negated) **/ |
||
102 | const WHERE_NMATCH = '!match'; |
||
103 | |||
104 | /** |
||
105 | * Underlying array |
||
106 | * @var array The array of data for this collection |
||
107 | */ |
||
108 | protected $data = []; |
||
109 | |||
110 | /** |
||
111 | * Collection constructor. |
||
112 | * |
||
113 | * Set the data for this collection using $data |
||
114 | * |
||
115 | * @param array|Iterator|null $data Either an array or an object that can be accessed |
||
116 | * as if it were an array. |
||
117 | */ |
||
118 | 127 | public function __construct($data = null) |
|
119 | { |
||
120 | 127 | $this->assertArrayOrIterator($data); |
|
121 | 126 | if (!is_null($data)) { |
|
122 | 125 | $this->setData($data); |
|
123 | 125 | } |
|
124 | 126 | } |
|
125 | |||
126 | /** |
||
127 | * Invokes the object as a function. |
||
128 | * |
||
129 | * If called with no arguments, it will return underlying data array |
||
130 | * If called with array as first argument, array will be merged into data array |
||
131 | * If called with second param, it will call $this->set($key, $val) |
||
132 | * If called with null as first param and key as second param, it will call $this->offsetUnset($key) |
||
133 | * |
||
134 | * @param null|array $val If an array, it will be merged into the collection |
||
135 | * If both this arg and second arg are null, underlying data array will be returned |
||
136 | * @param null|mixed $key If null and first arg is callable, this method will call map with callable |
||
137 | * If this value is not null but first arg is, it will call $this->offsetUnset($key) |
||
138 | * If this value is not null and first arg is anything other than callable, it will return $this->set($key, $val) |
||
139 | * @see the description for various possible method signatures |
||
140 | * @return mixed The return value depends entirely upon the arguments passed |
||
141 | * to it. See description for various possible arguments/return value combinations |
||
142 | */ |
||
143 | 6 | public function __invoke($val = null, $key = null) |
|
144 | { |
||
145 | 6 | if (is_null($val)) { |
|
146 | 3 | if (is_null($key)) { |
|
147 | 3 | return $this->data; |
|
148 | } else { |
||
149 | 1 | return $this->offsetUnset($key); |
|
150 | } |
||
151 | } else { |
||
152 | 4 | if (is_null($key)) { |
|
153 | 3 | if (is_array($val)) return $this->merge($val); |
|
154 | else { |
||
155 | 2 | if (is_callable($val)) { |
|
156 | 2 | return $this->map($val); |
|
157 | } |
||
158 | } |
||
159 | } else { |
||
160 | 1 | $this->offsetSet($key, $val); |
|
161 | } |
||
162 | } |
||
163 | 1 | return $this; |
|
164 | } |
||
165 | |||
166 | /** |
||
167 | * Set internal collection data. |
||
168 | * |
||
169 | * Use an array or iterator to set this collection's data. |
||
170 | * |
||
171 | * @param array|Iterator $data The data to set for this collection |
||
172 | * @return $this |
||
173 | * @throws InvalidArgumentException If invalid data type |
||
174 | */ |
||
175 | 125 | protected function setData($data) |
|
176 | { |
||
177 | 125 | $this->assertArrayOrIterator($data); |
|
178 | 125 | foreach ($data as $key => $val) { |
|
179 | 125 | $this->data[$key] = $val; |
|
180 | 125 | } |
|
181 | 125 | return $this; |
|
182 | } |
||
183 | |||
184 | /** |
||
185 | * Get data as an array. |
||
186 | * |
||
187 | * @return array Collection data as an array |
||
188 | */ |
||
189 | 63 | public function toArray() |
|
190 | { |
||
191 | 63 | $data = []; |
|
192 | 63 | foreach($this->data as $key => $val) { |
|
193 | 63 | $data[$key] = (is_object($val) && method_exists($val, 'toArray')) ? $val->toArray() : $val; |
|
194 | 63 | } |
|
195 | 63 | return $data; |
|
196 | } |
||
197 | |||
198 | /** |
||
199 | * Get array keys |
||
200 | * |
||
201 | * @return Collection The collection's keys (as a collection) |
||
202 | */ |
||
203 | 3 | public function keys() |
|
204 | { |
||
205 | 3 | return new self(array_keys($this->data)); |
|
206 | } |
||
207 | |||
208 | /** |
||
209 | * Merge data (array or iterator) |
||
210 | * |
||
211 | * Pass an array to this method to have it merged into the collection. A new |
||
212 | * collection will be created with the merged data and returned. |
||
213 | * |
||
214 | * @param array|iterator $data Data to merge into the collection |
||
215 | * @param boolean $overwrite Whether existing values should be overwritten |
||
216 | * @return Collection A new collection with $data merged into it |
||
217 | */ |
||
218 | 2 | public function merge($data = null, $overwrite = true) |
|
219 | { |
||
220 | 2 | $this->assertArrayOrIterator($data); |
|
221 | 2 | $coll = new self($this->data); |
|
222 | 2 | if (is_null($data)) { |
|
223 | return $coll; |
||
224 | } |
||
225 | 2 | foreach ($data as $key => $val) { |
|
226 | 2 | $coll->set($key, $val, $overwrite); |
|
227 | 2 | } |
|
228 | 2 | return $coll; |
|
229 | } |
||
230 | |||
231 | /** |
||
232 | * Test whether this collection contains the given value, optionally at a |
||
233 | * specific key. |
||
234 | * |
||
235 | * This will return true if the collection contains a value equivalent to $val. |
||
236 | * If $val is a callable (function/method), than the callable will be called |
||
237 | * with $val, $key as its arguments (in that order). If the callable returns |
||
238 | * any truthy value, than this method will return true. |
||
239 | * |
||
240 | * @param mixed|callable $val Either the value to check for or a callable that |
||
241 | * accepts $key,$val and returns true if collection contains $val |
||
242 | * @param mixed $key If not null, the only the value for this key will be checked |
||
243 | * @return boolean True if this collection contains $val, $key |
||
244 | */ |
||
245 | 49 | public function contains($val, $key = null) |
|
246 | { |
||
247 | 49 | if (is_callable($callback = $val)) { |
|
248 | 48 | foreach ($this->data as $key => $val) { |
|
249 | 48 | if ($callback($val, $key)) return true; |
|
250 | 40 | } |
|
251 | 42 | } elseif (in_array($val, $this->data)) { |
|
252 | 9 | return (is_null($key) || (isset($this->data[$key]) && $this->data[$key] == $val)); |
|
253 | } |
||
254 | 42 | return false; |
|
255 | } |
||
256 | |||
257 | /** |
||
258 | * Tabular Where Search. |
||
259 | * |
||
260 | * Search for values of a certain key that meet a particular search criteria |
||
261 | * using either one of the "Collection::WHERE_" class constants, or its string |
||
262 | * counterpart. |
||
263 | * |
||
264 | * Warning: Only works for tabular collections (2-dimensional data array) |
||
265 | * |
||
266 | * @param string $key The key to compare to $val |
||
267 | * @param mixed|Callable $val Either a value to test against or a callable to |
||
268 | * run your own custom "where comparison logic" |
||
269 | * @param string $comp The type of comparison operation ot use (such as "==" |
||
270 | * or "instanceof"). Must be one of the self::WHERE_* constants' values |
||
271 | * listed at the top of this class. |
||
272 | * @return Collection A collection of rows that meet the criteria |
||
273 | * specified by $key, $val, and $comp |
||
274 | */ |
||
275 | 4 | public function where($key, $val, $comp = null) |
|
276 | { |
||
277 | 4 | $this->assertIsTabular(); |
|
278 | 3 | $data = []; |
|
279 | 3 | if ($this->has($key, true)) { |
|
280 | 3 | if (is_callable($val)) { |
|
281 | 1 | foreach ($this->data as $ln => $row) { |
|
282 | 1 | if ($val($row[$key], $key)) { |
|
283 | 1 | $data[$ln] = $row; |
|
284 | 1 | } |
|
285 | 1 | } |
|
286 | 1 | } else { |
|
287 | 3 | foreach ($this->data as $ln => $row) { |
|
288 | 3 | $fieldval = $row[$key]; |
|
289 | 3 | switch (strtolower($comp)) { |
|
290 | 3 | case self::WHERE_ID: |
|
291 | 1 | $comparison = $fieldval === $val; |
|
292 | 1 | break; |
|
293 | 3 | case self::WHERE_NID: |
|
294 | 1 | $comparison = $fieldval !== $val; |
|
295 | 1 | break; |
|
296 | 3 | case self::WHERE_LT: |
|
297 | $comparison = $fieldval < $val; |
||
298 | break; |
||
299 | 3 | case self::WHERE_LTE: |
|
300 | 1 | $comparison = $fieldval <= $val; |
|
301 | 1 | break; |
|
302 | 3 | case self::WHERE_GT: |
|
303 | 1 | $comparison = $fieldval > $val; |
|
304 | 1 | break; |
|
305 | 3 | case self::WHERE_GTE: |
|
306 | $comparison = $fieldval >= $val; |
||
307 | break; |
||
308 | 3 | case self::WHERE_LIKE: |
|
309 | 1 | $comparison = strtolower($fieldval) == strtolower($val); |
|
310 | 1 | break; |
|
311 | 3 | case self::WHERE_NLIKE: |
|
312 | 1 | $comparison = strtolower($fieldval) != strtolower($val); |
|
313 | 1 | break; |
|
314 | 3 | case self::WHERE_ISA: |
|
315 | 1 | $comparison = (is_object($fieldval) && $fieldval instanceof $val); |
|
316 | 1 | break; |
|
317 | 3 | case self::WHERE_NISA: |
|
318 | 1 | $comparison = (!is_object($fieldval) || !($fieldval instanceof $val)); |
|
319 | 1 | break; |
|
320 | 3 | case self::WHERE_TOF: |
|
321 | 1 | $comparison = (strtolower(gettype($fieldval)) == strtolower($val)); |
|
322 | 1 | break; |
|
323 | 3 | case self::WHERE_NTOF: |
|
324 | 1 | $comparison = (strtolower(gettype($fieldval)) != strtolower($val)); |
|
325 | 1 | break; |
|
326 | 3 | case self::WHERE_NEQ: |
|
327 | 1 | $comparison = $fieldval != $val; |
|
328 | 1 | break; |
|
329 | 2 | case self::WHERE_MATCH: |
|
330 | 1 | $match = preg_match($val, $fieldval); |
|
331 | 1 | $comparison = $match === 1; |
|
332 | 1 | break; |
|
333 | 2 | case self::WHERE_NMATCH: |
|
334 | 1 | $match = preg_match($val, $fieldval); |
|
335 | 1 | $comparison = $match === 0; |
|
336 | 1 | break; |
|
337 | 1 | case self::WHERE_EQ: |
|
338 | 1 | default: |
|
339 | 1 | $comparison = $fieldval == $val; |
|
340 | 1 | break; |
|
341 | 3 | } |
|
342 | 3 | if ($comparison) { |
|
343 | 3 | $data[$ln] = $row; |
|
344 | 3 | } |
|
345 | 3 | } |
|
346 | } |
||
347 | 3 | } |
|
348 | 3 | return new self($data); |
|
349 | } |
||
350 | |||
351 | /** |
||
352 | * Get the key at a given numerical position. |
||
353 | * |
||
354 | * This method will give you the key at the specified numerical offset, |
||
355 | * regardless of how it's indexed (associatively, unordered numerical, etc.). |
||
356 | * This allows you to find out what the first key is. Or the second. etc. |
||
357 | * |
||
358 | * @param int $pos Numerical position |
||
359 | * @return mixed The key at numerical position |
||
360 | * @throws \OutOfBoundsException If you request a position that doesn't exist |
||
361 | * @todo Allow negative $pos to start counting from end |
||
362 | */ |
||
363 | 66 | public function getKeyAtPosition($pos) |
|
364 | { |
||
365 | 66 | $i = 0; |
|
366 | 66 | foreach ($this->data as $key => $val) { |
|
367 | 66 | if ($i === $pos) return $key; |
|
368 | 13 | $i++; |
|
369 | 18 | } |
|
370 | 17 | throw new OutOfBoundsException("Collection data does not contain a key at given position: " . $pos); |
|
371 | } |
||
372 | |||
373 | /** |
||
374 | * Get the value at a given numerical position. |
||
375 | * |
||
376 | * This method will give you the value at the specified numerical offset, |
||
377 | * regardless of how it's indexed (associatively, unordered numerical, etc.). |
||
378 | * This allows you to find out what the first value is. Or the second. etc. |
||
379 | * |
||
380 | * @param int $pos Numerical position |
||
381 | * @return mixed The value at numerical position |
||
382 | * @throws \OutOfBoundsException If you request a position that doesn't exist |
||
383 | * @todo Allow negative $pos to start counting from end |
||
384 | */ |
||
385 | 65 | public function getValueAtPosition($pos) |
|
386 | { |
||
387 | 65 | return $this->data[$this->getKeyAtPosition($pos)]; |
|
388 | } |
||
389 | |||
390 | /** |
||
391 | * Determine if this collection has a value at the specified numerical position. |
||
392 | * |
||
393 | * @param int $pos Numerical position |
||
394 | * @return boolean Whether there exists a value at specified position |
||
395 | */ |
||
396 | 58 | public function hasPosition($pos) |
|
397 | { |
||
398 | try { |
||
399 | 58 | $this->getKeyAtPosition($pos); |
|
400 | 58 | } catch (OutOfBoundsException $e) { |
|
401 | 9 | return false; |
|
402 | } |
||
403 | 58 | return true; |
|
404 | } |
||
405 | |||
406 | /** |
||
407 | * "Pop" an item from the end of a collection. |
||
408 | * |
||
409 | * Removes an item from the bottom of the collection's underlying array and |
||
410 | * returns it. This will actually remove the item from the collection. |
||
411 | * |
||
412 | * @param boolean $discard Whether to discard the popped item and return |
||
413 | * $this instead of the default behavior |
||
414 | * @return mixed Whatever the last item in the collection is |
||
415 | */ |
||
416 | 1 | public function pop($discard = false) |
|
417 | { |
||
418 | 1 | $popped = array_pop($this->data); |
|
419 | 1 | return ($discard) ? $this : $popped; |
|
420 | } |
||
421 | |||
422 | /** |
||
423 | * "Shift" an item from the top of a collection. |
||
424 | * |
||
425 | * Removes an item from the top of the collection's underlying array and |
||
426 | * returns it. This will actually remove the item from the collection. |
||
427 | * |
||
428 | * @param boolean $discard Whether to discard the shifted item and return |
||
429 | * $this instead of the default behavior |
||
430 | * @return mixed Whatever the first item in the collection is |
||
431 | */ |
||
432 | 22 | public function shift($discard = false) |
|
433 | { |
||
434 | 22 | $shifted = array_shift($this->data); |
|
435 | 22 | return ($discard) ? $this : $shifted; |
|
436 | } |
||
437 | |||
438 | /** |
||
439 | * "Push" an item onto the end of the collection. |
||
440 | * |
||
441 | * Adds item(s) to the end of the collection's underlying array. |
||
442 | * |
||
443 | * @param mixed ... The item(s) to push onto the end of the collection. You may |
||
444 | * also add additional arguments to push multiple items onto the end |
||
445 | * @return $this |
||
446 | */ |
||
447 | 22 | public function push() |
|
448 | { |
||
449 | 22 | foreach (func_get_args() as $arg) { |
|
450 | 22 | array_push($this->data, $arg); |
|
451 | 22 | } |
|
452 | 22 | return $this; |
|
453 | } |
||
454 | |||
455 | /** |
||
456 | * "Unshift" an item onto the beginning of the collection. |
||
457 | * |
||
458 | * Adds item(s) to the beginning of the collection's underlying array. |
||
459 | * |
||
460 | * @param mixed ... The item(s) to push onto the top of the collection. You may |
||
461 | * also add additional arguments to add multiple items |
||
462 | * @return $this |
||
463 | */ |
||
464 | 1 | public function unshift() |
|
465 | { |
||
466 | 1 | foreach (array_reverse(func_get_args()) as $arg) { |
|
467 | 1 | array_unshift($this->data, $arg); |
|
468 | 1 | } |
|
469 | 1 | return $this; |
|
470 | } |
||
471 | |||
472 | /** |
||
473 | * "Insert" an item at a given numerical position. |
||
474 | * |
||
475 | * Regardless of how the collection is keyed (numerically or otherwise), this |
||
476 | * method will insert an item at a given numerical position. If the given |
||
477 | * position is more than there are items in the collection, the given item |
||
478 | * will simply be added to the end. Nothing is overwritten with this method. |
||
479 | * All elements that come after $offset will simply be shifted a space. |
||
480 | * |
||
481 | * Note: This method is one of the few that will modify the collection in |
||
482 | * place rather than returning a new one. |
||
483 | * |
||
484 | * @param int $offset The offset (position) at which you want to insert an item |
||
485 | * @param mixed $item The item(s) to push onto the top of the collection |
||
486 | * @return $this |
||
487 | */ |
||
488 | 1 | public function insert($offset, $item) |
|
489 | { |
||
490 | 1 | $top = array_slice($this->data, 0, $offset); |
|
491 | 1 | $bottom = array_slice($this->data, $offset); |
|
492 | 1 | $this->data = array_merge($top, [$item], $bottom); |
|
493 | 1 | return $this; |
|
494 | } |
||
495 | |||
496 | /** |
||
497 | * Pad collection to specified length. |
||
498 | * |
||
499 | * Pad the collection to a specific length, filling it with a given value. A |
||
500 | * new collection with padded values is returned. |
||
501 | * |
||
502 | * @param int $size The number of values you want this collection to have |
||
503 | * @param mixed $with The value you want to pad the collection with |
||
504 | * @return Collection A new collection, padded to specified size |
||
505 | */ |
||
506 | 1 | public function pad($size, $with = null) |
|
507 | { |
||
508 | 1 | return new self(array_pad($this->data, (int) $size, $with)); |
|
509 | } |
||
510 | |||
511 | /** |
||
512 | * Check if this collection has a value at the given key. |
||
513 | * |
||
514 | * If this is a tabular data collection, this will check if the table has the |
||
515 | * given key by default. You can change this behavior by passing false as the |
||
516 | * second argument (this will change the behavior to check for a given key |
||
517 | * at the row-level so it will likely only ever be numerical). |
||
518 | * |
||
519 | * @param mixed $key The key you want to check |
||
520 | * @param bool $column True if you want to check a specific column |
||
521 | * @return bool Whether there's a value at $key |
||
522 | */ |
||
523 | 27 | public function has($key, $column = true) |
|
524 | { |
||
525 | // we only need to check one row for the existance of $key because the |
||
526 | // isTabular() method ensures every row has the same keys |
||
527 | 27 | if ($column && $this->isTabular() && $first = reset($this->data)) { |
|
528 | 3 | return array_key_exists($key, $first); |
|
529 | } |
||
530 | // if we don't have tabular data or we don't want to check for a column... |
||
531 | 24 | return array_key_exists($key, $this->data); |
|
532 | } |
||
533 | |||
534 | /** |
||
535 | * Get the value at the given key. |
||
536 | * |
||
537 | * If there is a value at the given key, it will be returned. If there isn't, |
||
538 | * a default may be specified. If you would like for this method to throw an |
||
539 | * exception when there is no value at $key, pass true as the third argument |
||
540 | * |
||
541 | * @param mixed $key The key you want to test for |
||
542 | * @param mixed $default The default to return if there is no value at $key |
||
543 | * @param boolean $throwExc Whether to throw an exception on failure to find |
||
544 | * a value at the given key. |
||
545 | * @return mixed Either the value at $key or the specified default |
||
546 | * value |
||
547 | * @throws \OutOfBoundsException If value can't be found at $key and $throwExc |
||
548 | * is set to true |
||
549 | */ |
||
550 | 33 | public function get($key, $default = null, $throwExc = false) |
|
551 | { |
||
552 | 33 | if (array_key_exists($key, $this->data)) { |
|
553 | 31 | return $this->data[$key]; |
|
554 | } else { |
||
555 | 7 | if ($throwExc) { |
|
556 | 6 | throw new OutOfBoundsException("Collection data does not contain value for given key: " . $key); |
|
557 | } |
||
558 | } |
||
559 | 2 | return $default; |
|
560 | } |
||
561 | |||
562 | /** |
||
563 | * Set value for the given key. |
||
564 | * |
||
565 | * Given $key, this will set $this->data[$key] to the value of $val. If that |
||
566 | * index already has a value, it will be overwritten unless $overwrite is set |
||
567 | * to false. In that case nothing happens. |
||
568 | * |
||
569 | * @param string $key The key you want to set a value for |
||
570 | * @param mixed $value The value you want to set key to |
||
571 | * @param boolean $overwrite Whether to overwrite existing value |
||
572 | * @return $this |
||
573 | */ |
||
574 | 26 | public function set($key, $value = null, $overwrite = true) |
|
575 | { |
||
576 | 26 | if (!array_key_exists($key, $this->data) || $overwrite) { |
|
577 | 26 | $this->data[$key] = $value; |
|
578 | 26 | } |
|
579 | 26 | return $this; |
|
580 | } |
||
581 | |||
582 | /** |
||
583 | * Unset value at the given offset. |
||
584 | * |
||
585 | * This method is used when the end-user uses a colleciton as an array and |
||
586 | * calls unset($collection[5]). |
||
587 | * |
||
588 | * @param mixed $offset The offset at which to unset |
||
589 | * @return $this |
||
590 | * @todo create an alias for this... maybe delete() or remove() |
||
591 | */ |
||
592 | 2 | public function offsetUnset($offset) |
|
593 | { |
||
594 | 2 | if ($this->has($offset)) { |
|
595 | 2 | unset($this->data[$offset]); |
|
596 | 2 | } |
|
597 | 2 | return $this; |
|
598 | } |
||
599 | |||
600 | /** |
||
601 | * Alias of self::has |
||
602 | * |
||
603 | * @param int|mixed The offset to test for |
||
604 | * @return boolean Whether a value exists at $offset |
||
605 | */ |
||
606 | public function offsetExists($offset) |
||
607 | { |
||
608 | return $this->has($offset); |
||
609 | } |
||
610 | |||
611 | /** |
||
612 | * Alias of self::set |
||
613 | * |
||
614 | * @param int|mixed $offset The offset to set |
||
615 | * @param mixed $value The value to set it to |
||
616 | * @return Collection |
||
617 | */ |
||
618 | 1 | public function offsetSet($offset, $value) |
|
619 | { |
||
620 | 1 | $this->set($offset, $value); |
|
621 | 1 | return $this; |
|
622 | } |
||
623 | |||
624 | /** |
||
625 | * Alias of self::get |
||
626 | * |
||
627 | * @param int|mixed The offset to get |
||
628 | * @return mixed The value at $offset |
||
629 | */ |
||
630 | public function offsetGet($offset) |
||
631 | { |
||
632 | return $this->get($offset); |
||
633 | } |
||
634 | |||
635 | /** |
||
636 | * Increment an item. |
||
637 | * |
||
638 | * Increment the item specified by $key by one value. Intended for integers |
||
639 | * but also works (using this term loosely) for letters. Any other data type |
||
640 | * it may modify is unintended behavior at best. |
||
641 | * |
||
642 | * This method modifies its internal data array rather than returning a new |
||
643 | * collection. |
||
644 | * |
||
645 | * @param mixed $key The key of the item you want to increment. |
||
646 | * @return $this |
||
647 | */ |
||
648 | 3 | public function increment($key) |
|
649 | { |
||
650 | 3 | $val = $this->get($key, null, true); |
|
651 | 3 | $this->set($key, ++$val); |
|
652 | 3 | return $this; |
|
653 | } |
||
654 | |||
655 | /** |
||
656 | * Decrement an item. |
||
657 | * |
||
658 | * Frcrement the item specified by $key by one value. Intended for integers. |
||
659 | * Does not work for letters and if it does anything to anything else, it's |
||
660 | * unintended at best. |
||
661 | * |
||
662 | * This method modifies its internal data array rather than returning a new |
||
663 | * collection. |
||
664 | * |
||
665 | * @param mixed $key The key of the item you want to decrement. |
||
666 | * @return $this |
||
667 | */ |
||
668 | 1 | public function decrement($key) |
|
669 | { |
||
670 | 1 | $val = $this->get($key, null, true); |
|
671 | 1 | $this->set($key, --$val); |
|
672 | 1 | return $this; |
|
673 | } |
||
674 | |||
675 | /** |
||
676 | * Count the items in this collection. |
||
677 | * |
||
678 | * Returns either the number of items in the collection or, if this is a |
||
679 | * collection of tabular data, and you pass true as the first argument, you |
||
680 | * will get back a collection containing the count of each row (which will |
||
681 | * always be the same so maybe I should still just return an integer). |
||
682 | * |
||
683 | * @param boolean $multi Whether to count just the items in the collection or |
||
684 | * to count the items in each tabular data row. |
||
685 | * @return string Either an integer count or a collection of counts |
||
686 | */ |
||
687 | 42 | public function count($multi = false) |
|
688 | { |
||
689 | 42 | if ($multi) { |
|
690 | // if every value is an array... |
||
691 | 1 | if (false !== ($condRet = $this->if2DMapInternalMethod(__METHOD__))) { |
|
692 | 1 | return $condRet; |
|
693 | } |
||
694 | } |
||
695 | // just count main array |
||
696 | 42 | return count($this->data); |
|
697 | } |
||
698 | |||
699 | /** |
||
700 | * Collection map. |
||
701 | * |
||
702 | * Apply a callback to each element in the collection and return the |
||
703 | * resulting collection. The resulting collection will contain the return |
||
704 | * values of each call to $callback. |
||
705 | * |
||
706 | * @param Callable $callback A callback to apply to each item in the collection |
||
707 | * @return Collection A collection of callback return values |
||
708 | */ |
||
709 | 34 | public function map(Callable $callback) |
|
710 | { |
||
711 | 34 | return new self(array_map($callback, $this->data)); |
|
712 | } |
||
713 | |||
714 | /** |
||
715 | * Walk the collection. |
||
716 | * |
||
717 | * Walk through each item in the collection, calling a function for each |
||
718 | * item in the collection. This is one of the few methods that doesn't return |
||
719 | * a new collection. All changes will be to the existing collection object. |
||
720 | * |
||
721 | * Note: return false from the collback to stop walking. |
||
722 | * |
||
723 | * @param Callable $callback A callback function to call for each item in the collection |
||
724 | * @param mixed $userdata Any extra data you'd like passed to your callback |
||
725 | * @return $this |
||
726 | */ |
||
727 | 34 | public function walk(Callable $callback, $userdata = null) |
|
728 | { |
||
729 | 34 | array_walk($this->data, $callback, $userdata); |
|
730 | 34 | return $this; |
|
731 | } |
||
732 | |||
733 | /** |
||
734 | * Call a user function for each item in the collection. If function returns |
||
735 | * false, loop is terminated. |
||
736 | * |
||
737 | * @param callable $callback The callback function to call for each item |
||
738 | * @return $this |
||
739 | * @todo I'm not entirely sure what this method should do... return new |
||
740 | * collection? modify this one? |
||
741 | * @todo This method appears to be a duplicate of walk(). Is it even necessary? |
||
742 | */ |
||
743 | 2 | public function each(Callable $callback) |
|
744 | { |
||
745 | 2 | foreach ($this->data as $key => $val) { |
|
746 | 2 | if (!$ret = $callback($val, $key)) { |
|
747 | 2 | if ($ret === false) break; |
|
748 | 2 | } |
|
749 | 2 | } |
|
750 | 2 | return $this; |
|
751 | } |
||
752 | |||
753 | /** |
||
754 | * Reduce collection to single value. |
||
755 | * |
||
756 | * Reduces the collection to a single value by calling a callback for each |
||
757 | * item in the collection, carrying along an accumulative value as it does so. |
||
758 | * The final value is then returned. |
||
759 | * |
||
760 | * @param Callable $callback The function to reduce the collection |
||
761 | * @param mixed $initial The initial value to set the accumulative value to |
||
762 | * @return mixed Whatever the final value from the callback is |
||
763 | */ |
||
764 | public function reduce(Callable $callback, $initial = null) |
||
768 | |||
769 | /** |
||
770 | * Filter out unwanted items using a callback function. |
||
771 | * |
||
772 | * @param Callable $callback |
||
773 | * @return Collection A new collection with filtered items removed |
||
774 | */ |
||
775 | 23 | public function filter(Callable $callback) |
|
783 | |||
784 | /** |
||
785 | * Get first match. |
||
786 | * |
||
787 | * Get first value that meets criteria specified with $callback function. |
||
788 | * |
||
789 | * @param Callable $callback A callback with arguments ($val, $key). If it |
||
790 | * returns true, that $val will be returned. |
||
791 | * @return mixed The first $val that meets criteria specified with $callback |
||
792 | */ |
||
793 | 1 | public function first(Callable $callback) |
|
794 | { |
||
795 | 1 | foreach ($this->data as $key => $val) { |
|
796 | 1 | if ($callback($val, $key)) return $val; |
|
797 | 1 | } |
|
798 | return null; |
||
799 | } |
||
800 | |||
801 | /** |
||
802 | * Get last match. |
||
803 | * |
||
804 | * Get last value that meets criteria specified with $callback function. |
||
805 | * |
||
806 | * @param Callable $callback A callback with arguments ($val, $key). If it |
||
807 | * returns true, that $val will be returned. |
||
808 | * @return mixed The last $val that meets criteria specified with $callback |
||
809 | */ |
||
810 | 1 | public function last(Callable $callback) |
|
811 | { |
||
812 | 1 | $elem = null; |
|
813 | 1 | foreach ($this->data as $key => $val) { |
|
814 | 1 | if ($callback($val, $key)) $elem = $val; |
|
815 | 1 | } |
|
816 | 1 | return $elem; |
|
817 | } |
||
818 | |||
819 | /** |
||
820 | * Collection value frequency. |
||
821 | * |
||
822 | * Returns an array where the key is a value in the collection and the value |
||
823 | * is the number of times that value appears in the collection. |
||
824 | * |
||
825 | * @return Collection A collection of value frequencies (see description) |
||
826 | */ |
||
827 | 23 | public function frequency() |
|
842 | |||
843 | /** |
||
844 | * Unique collection. |
||
845 | * |
||
846 | * Returns a collection with duplicate values removed. If two-dimensional, |
||
847 | * then each array within the collection will have its duplicates removed. |
||
848 | * |
||
849 | * @return Collection A new collection with duplicate values removed. |
||
850 | */ |
||
851 | 23 | public function unique() |
|
858 | |||
859 | /** |
||
860 | * Get duplicate values. |
||
861 | * |
||
862 | * Returns a collection of arrays where the key is the duplicate value |
||
863 | * and the value is an array of keys from the original collection. |
||
864 | * |
||
865 | * @return Collection A new collection with duplicate values. |
||
866 | */ |
||
867 | 7 | public function duplicates() |
|
877 | |||
878 | /** |
||
879 | * Reverse keys/values. |
||
880 | * |
||
881 | * Get a new collection where the keys and values have been swapped. |
||
882 | * |
||
883 | * @return Collection A new collection where keys/values have been swapped |
||
884 | */ |
||
885 | 1 | public function flip() |
|
886 | { |
||
887 | 1 | return new self(array_flip($this->data)); |
|
888 | } |
||
889 | |||
890 | /** |
||
891 | * Return an array of key/value pairs. |
||
892 | * |
||
893 | * Return array can either be in [key,value] or [key => value] format. The |
||
894 | * first is the default. |
||
895 | * |
||
896 | * @param boolean $alt Whether you want pairs in [k => v] rather than [k, v] format |
||
897 | * @return Collection A collection of key/value pairs |
||
898 | */ |
||
899 | 1 | public function pairs($alt = false) |
|
900 | { |
||
901 | 1 | return new self(array_map( |
|
902 | function ($key, $val) use ($alt) { |
||
903 | 1 | if ($alt) { |
|
904 | 1 | return [$key => $val]; |
|
905 | } else { |
||
906 | 1 | return [$key, $val]; |
|
907 | } |
||
908 | 1 | }, |
|
909 | 1 | array_keys($this->data), |
|
910 | 1 | array_values($this->data) |
|
911 | 1 | )); |
|
912 | } |
||
913 | |||
914 | /** |
||
915 | * Get average of data items. |
||
916 | * |
||
917 | * @return mixed The average of all items in collection |
||
918 | */ |
||
919 | 2 | public function sum() |
|
920 | { |
||
921 | 2 | if (false !== ($condRet = $this->if2DMapInternalMethod(__METHOD__))) { |
|
922 | 1 | return $condRet; |
|
923 | } |
||
924 | 2 | $this->assertNumericValues(); |
|
925 | 2 | return array_sum($this->data); |
|
926 | } |
||
927 | |||
928 | /** |
||
929 | * Get average of data items. |
||
930 | * |
||
931 | * If two-dimensional it will return a collection of averages. |
||
932 | * |
||
933 | * @return mixed|Collection The average of all items in collection |
||
934 | */ |
||
935 | 3 | public function average() |
|
945 | |||
946 | /** |
||
947 | * Get largest item in the collection |
||
948 | * |
||
949 | * @return mixed The largest item in the collection |
||
950 | */ |
||
951 | 9 | public function max() |
|
952 | { |
||
953 | 9 | if (false !== ($condRet = $this->if2DMapInternalMethod(__METHOD__))) { |
|
954 | 1 | return $condRet; |
|
955 | } |
||
956 | 9 | $this->assertNumericValues(); |
|
957 | 9 | return max($this->data); |
|
958 | } |
||
959 | |||
960 | /** |
||
961 | * Get smallest item in the collection |
||
962 | * |
||
963 | * @return mixed The smallest item in the collection |
||
964 | */ |
||
965 | 5 | public function min() |
|
966 | { |
||
967 | 5 | if (false !== ($condRet = $this->if2DMapInternalMethod(__METHOD__))) { |
|
968 | 1 | return $condRet; |
|
969 | } |
||
970 | 5 | $this->assertNumericValues(); |
|
971 | 5 | return min($this->data); |
|
972 | } |
||
973 | |||
974 | /** |
||
975 | * Get mode of data items. |
||
976 | * |
||
977 | * @return mixed The mode of all items in collection |
||
978 | */ |
||
979 | 9 | public function mode() |
|
993 | |||
994 | /** |
||
995 | * Get median of data items. |
||
996 | * |
||
997 | * @return mixed The median of all items in collection |
||
998 | */ |
||
999 | 2 | public function median() |
|
1000 | { |
||
1001 | 2 | if (false !== ($condRet = $this->if2DMapInternalMethod(__METHOD__))) { |
|
1002 | 1 | return $condRet; |
|
1003 | } |
||
1004 | 2 | $this->assertNumericValues(); |
|
1005 | 2 | $count = count($this->data); |
|
1006 | 2 | natcasesort($this->data); |
|
1007 | 2 | $middle = ($count / 2); |
|
1008 | 2 | $values = array_values($this->data); |
|
1009 | 2 | if ($count % 2 == 0) { |
|
1010 | // even number, use middle |
||
1011 | 2 | $low = $values[$middle - 1]; |
|
1012 | 2 | $high = $values[$middle]; |
|
1013 | 2 | return ($low + $high) / 2; |
|
1014 | } |
||
1015 | // odd number return median |
||
1016 | 2 | return $values[$middle]; |
|
1017 | } |
||
1018 | |||
1019 | /** |
||
1020 | * Join items together into a string |
||
1021 | * |
||
1022 | * @param string $glue The string to join items together with |
||
1023 | * @return string A string with all items in the collection strung together |
||
1024 | * @todo Make this work with 2D collection |
||
1025 | */ |
||
1026 | 18 | public function join($glue) |
|
1030 | |||
1031 | /** |
||
1032 | * Is the collection empty? |
||
1033 | * |
||
1034 | * @return boolean Whether the collection is empty |
||
1035 | */ |
||
1036 | 1 | public function isEmpty() |
|
1037 | { |
||
1038 | 1 | return empty($this->data); |
|
1039 | } |
||
1040 | |||
1041 | /** |
||
1042 | * Immediately invoke a callback. |
||
1043 | * |
||
1044 | * @param Callable $callback A callback to invoke with ($this) |
||
1045 | * @return mixed Whatever the callback returns |
||
1046 | */ |
||
1047 | 1 | public function value(Callable $callback) |
|
1048 | { |
||
1049 | 1 | return $callback($this); |
|
1050 | } |
||
1051 | |||
1052 | /** |
||
1053 | * Sort the collection. |
||
1054 | * |
||
1055 | * This method can sort your collection in any which way you please. By |
||
1056 | * default it uses a case-insensitive natural order algorithm, but you can |
||
1057 | * pass it any sorting algorithm you like. |
||
1058 | * |
||
1059 | * @param Callable $callback The sorting function you want to use |
||
1060 | * @param boolean $preserve_keys Whether you want to preserve keys |
||
1061 | * @return Collection A new collection sorted by $callback |
||
1062 | */ |
||
1063 | 23 | public function sort(Callable $callback = null, $preserve_keys = true) |
|
1064 | { |
||
1065 | 23 | if (is_null($callback)) $callback = 'strcasecmp'; |
|
1066 | 23 | if (!is_callable($callback)) { |
|
1067 | throw new InvalidArgumentException(sprintf( |
||
1068 | 'Invalid argument supplied for %s. Expected %s, got: "%s".', |
||
1069 | __METHOD__, |
||
1070 | 'Callable', |
||
1071 | gettype($callback) |
||
1072 | )); |
||
1073 | } |
||
1074 | 23 | $data = $this->data; |
|
1075 | 23 | if ($preserve_keys) { |
|
1076 | 23 | uasort($data, $callback); |
|
1077 | 23 | } else { |
|
1078 | 2 | usort($data, $callback); |
|
1079 | } |
||
1080 | 23 | return new self($data); |
|
1081 | } |
||
1082 | |||
1083 | /** |
||
1084 | * Order tabular data. |
||
1085 | * |
||
1086 | * Order a tabular dataset by a given key/comparison algorithm |
||
1087 | * |
||
1088 | * @param string $key The key you want to order by |
||
1089 | * @param Callable $cmp The sorting comparison algorithm to use |
||
1090 | * @param boolean $preserve_keys Whether keys should be preserved |
||
1091 | * @return Collection A new collection sorted by $cmp and $key |
||
1092 | */ |
||
1093 | 1 | public function orderBy($key, Callable $cmp = null, $preserve_keys = true) |
|
1094 | { |
||
1095 | 1 | $this->assertIsTabular(); |
|
1096 | return $this->sort(function($a, $b) use ($key, $cmp) { |
||
1097 | 1 | if (!isset($a[$key]) || !isset($b[$key])) { |
|
1098 | throw new RuntimeException('Cannot order collection by non-existant key: ' . $key); |
||
1099 | } |
||
1100 | 1 | if (is_null($cmp)) { |
|
1101 | 1 | return strcasecmp($a[$key], $b[$key]); |
|
1102 | } else { |
||
1103 | 1 | return $cmp($a[$key], $b[$key]); |
|
1104 | } |
||
1105 | 1 | }, $preserve_keys); |
|
1106 | } |
||
1107 | |||
1108 | /** |
||
1109 | * Reverse collection order. |
||
1110 | * |
||
1111 | * Reverse the order of items in a collection. Sometimes it's easier than |
||
1112 | * trying to write a particular sorting algurithm that sorts forwards and back. |
||
1113 | * |
||
1114 | * @param boolean $preserve_keys Whether keys should be preserved |
||
1115 | * @return Collection A new collection in reverse order |
||
1116 | */ |
||
1117 | 22 | public function reverse($preserve_keys = true) |
|
1121 | |||
1122 | /** |
||
1123 | * Is method an internal 2D map internal method? |
||
1124 | * |
||
1125 | * This is an internal method used to check if a particular method is one of |
||
1126 | * the 2D map methods. |
||
1127 | * |
||
1128 | * @internal |
||
1129 | * @param string $method The method name to check |
||
1130 | * @return boolean True if method is a 2D map internal method |
||
1131 | */ |
||
1132 | 39 | protected function if2DMapInternalMethod($method) |
|
1133 | { |
||
1134 | 39 | if ($this->is2D()) { |
|
1135 | 29 | $method = explode('::', $method, 2); |
|
1136 | 29 | if (count($method) == 2) { |
|
1137 | 29 | $method = $method[1]; |
|
1138 | return $this->map(function($val) use ($method) { |
||
1139 | 29 | return (new self($val))->$method(); |
|
1140 | 29 | }); |
|
1141 | } |
||
1142 | } |
||
1143 | 38 | return false; |
|
1144 | } |
||
1145 | |||
1146 | /** |
||
1147 | * Is this collection two-dimensional |
||
1148 | * |
||
1149 | * If all items of the collection are arrays this will return true. |
||
1150 | * |
||
1151 | * @return boolean whether this is two-dimensional |
||
1152 | */ |
||
1153 | 47 | public function is2D() |
|
1154 | { |
||
1155 | return !$this->contains(function($val){ |
||
1156 | 47 | return !is_array($val); |
|
1157 | 47 | }); |
|
1158 | } |
||
1159 | |||
1160 | /** |
||
1161 | * Is this a tabular collection? |
||
1162 | * |
||
1163 | * If this is a two-dimensional collection with the same keys in every array, |
||
1164 | * this method will return true. |
||
1165 | * |
||
1166 | * @return boolean Whether this is a tabular collection |
||
1167 | */ |
||
1168 | 36 | public function isTabular() |
|
1198 | |||
1199 | /** |
||
1200 | * Assert this collection is two-dimensional. |
||
1201 | * |
||
1202 | * Although a collection must be two-dimensional to be tabular, the opposite |
||
1203 | * is not necessarily true. This will throw an exception if this collection |
||
1204 | * contains anything but arrays. |
||
1205 | * |
||
1206 | * @throws |
||
1207 | */ |
||
1208 | protected function assertIs2D() |
||
1214 | |||
1215 | 5 | protected function assertIsTabular() |
|
1221 | |||
1222 | protected function assertNumericValues() |
||
1234 | |||
1235 | 127 | protected function assertArrayOrIterator($data) |
|
1242 | } |
||
1243 |