Debian Codegraph @

vendor/doctrine/collections/src/ArrayCollection.php

raw
1 <?php
2
3 declare(strict_types=1);
4
5 namespace Doctrine\Common\Collections;
6
7 use ArrayIterator;
8 use Closure;
9 use Doctrine\Common\Collections\Expr\ClosureExpressionVisitor;
10 use ReturnTypeWillChange;
11 use Stringable;
12 use Traversable;
13
14 use function array_all;
15 use function array_any;
16 use function array_filter;
17 use function array_find;
18 use function array_key_exists;
19 use function array_keys;
20 use function array_map;
21 use function array_reduce;
22 use function array_reverse;
23 use function array_search;
24 use function array_slice;
25 use function array_values;
26 use function count;
27 use function current;
28 use function end;
29 use function in_array;
30 use function key;
31 use function next;
32 use function reset;
33 use function spl_object_hash;
34 use function uasort;
35
36 use const ARRAY_FILTER_USE_BOTH;
37
38 /**
39 * An ArrayCollection is a Collection implementation that wraps a regular PHP array.
40 *
41 * Warning: Using (un-)serialize() on a collection is not a supported use-case
42 * and may break when we change the internals in the future. If you need to
43 * serialize a collection use {@link toArray()} and reconstruct the collection
44 * manually.
45 *
46 * @phpstan-template TKey of array-key
47 * @phpstan-template T
48 * @template-implements Collection<TKey,T>
49 * @template-implements Selectable<TKey,T>
50 * @phpstan-consistent-constructor
51 */
52 class ArrayCollection implements Collection, Selectable, Stringable
53 {
54 /**
55 * An array containing the entries of this collection.
56 *
57 * @phpstan-var array<TKey,T>
58 * @var mixed[]
59 */
60 private array $elements = [];
61
62 /**
63 * Initializes a new ArrayCollection.
64 *
65 * @phpstan-param array<TKey,T> $elements
66 */
67 public function __construct(array $elements = [])
68 {
69 $this->elements = $elements;
70 }
71
72 /**
73 * {@inheritDoc}
74 */
75 public function toArray()
76 {
77 return $this->elements;
78 }
79
80 /**
81 * {@inheritDoc}
82 */
83 public function first()
84 {
85 return reset($this->elements);
86 }
87
88 /**
89 * Creates a new instance from the specified elements.
90 *
91 * This method is provided for derived classes to specify how a new
92 * instance should be created when constructor semantics have changed.
93 *
94 * @param array $elements Elements.
95 * @phpstan-param array<K,V> $elements
96 *
97 * @return static
98 * @phpstan-return static<K,V>
99 *
100 * @phpstan-template K of array-key
101 * @phpstan-template V
102 */
103 protected function createFrom(array $elements)
104 {
105 return new static($elements);
106 }
107
108 /**
109 * {@inheritDoc}
110 */
111 public function last()
112 {
113 return end($this->elements);
114 }
115
116 /**
117 * {@inheritDoc}
118 */
119 public function key()
120 {
121 return key($this->elements);
122 }
123
124 /**
125 * {@inheritDoc}
126 */
127 public function next()
128 {
129 return next($this->elements);
130 }
131
132 /**
133 * {@inheritDoc}
134 */
135 public function current()
136 {
137 return current($this->elements);
138 }
139
140 /**
141 * {@inheritDoc}
142 */
143 public function remove(string|int $key)
144 {
145 if (! isset($this->elements[$key]) && ! array_key_exists($key, $this->elements)) {
146 return null;
147 }
148
149 $removed = $this->elements[$key];
150 unset($this->elements[$key]);
151
152 return $removed;
153 }
154
155 /**
156 * {@inheritDoc}
157 */
158 public function removeElement(mixed $element)
159 {
160 $key = array_search($element, $this->elements, true);
161
162 if ($key === false) {
163 return false;
164 }
165
166 unset($this->elements[$key]);
167
168 return true;
169 }
170
171 /**
172 * Required by interface ArrayAccess.
173 *
174 * @param TKey $offset
175 *
176 * @return bool
177 */
178 #[ReturnTypeWillChange]
179 public function offsetExists(mixed $offset)
180 {
181 return $this->containsKey($offset);
182 }
183
184 /**
185 * Required by interface ArrayAccess.
186 *
187 * @param TKey $offset
188 *
189 * @return T|null
190 */
191 #[ReturnTypeWillChange]
192 public function offsetGet(mixed $offset)
193 {
194 return $this->get($offset);
195 }
196
197 /**
198 * Required by interface ArrayAccess.
199 *
200 * @param TKey|null $offset
201 * @param T $value
202 *
203 * @return void
204 */
205 #[ReturnTypeWillChange]
206 public function offsetSet(mixed $offset, mixed $value)
207 {
208 if ($offset === null) {
209 $this->add($value);
210
211 return;
212 }
213
214 /** @phpstan-var TKey $offset */
215 $this->set($offset, $value);
216 }
217
218 /**
219 * Required by interface ArrayAccess.
220 *
221 * @param TKey $offset
222 *
223 * @return void
224 */
225 #[ReturnTypeWillChange]
226 public function offsetUnset(mixed $offset)
227 {
228 $this->remove($offset);
229 }
230
231 /**
232 * {@inheritDoc}
233 */
234 public function containsKey(string|int $key)
235 {
236 return isset($this->elements[$key]) || array_key_exists($key, $this->elements);
237 }
238
239 /**
240 * {@inheritDoc}
241 */
242 public function contains(mixed $element)
243 {
244 return in_array($element, $this->elements, true);
245 }
246
247 /**
248 * {@inheritDoc}
249 */
250 public function exists(Closure $p)
251 {
252 return array_any(
253 $this->elements,
254 static fn (mixed $element, mixed $key): bool => (bool) $p($key, $element),
255 );
256 }
257
258 /**
259 * {@inheritDoc}
260 *
261 * @phpstan-param TMaybeContained $element
262 *
263 * @return int|string|false
264 * @phpstan-return (TMaybeContained is T ? TKey|false : false)
265 *
266 * @template TMaybeContained
267 */
268 public function indexOf($element)
269 {
270 return array_search($element, $this->elements, true);
271 }
272
273 /**
274 * {@inheritDoc}
275 */
276 public function get(string|int $key)
277 {
278 return $this->elements[$key] ?? null;
279 }
280
281 /**
282 * {@inheritDoc}
283 */
284 public function getKeys()
285 {
286 return array_keys($this->elements);
287 }
288
289 /**
290 * {@inheritDoc}
291 */
292 public function getValues()
293 {
294 return array_values($this->elements);
295 }
296
297 /**
298 * {@inheritDoc}
299 *
300 * @return int<0, max>
301 */
302 #[ReturnTypeWillChange]
303 public function count()
304 {
305 return count($this->elements);
306 }
307
308 /**
309 * {@inheritDoc}
310 */
311 public function set(string|int $key, mixed $value)
312 {
313 $this->elements[$key] = $value;
314 }
315
316 /**
317 * {@inheritDoc}
318 *
319 * This breaks assumptions about the template type, but it would
320 * be a backwards-incompatible change to remove this method
321 */
322 public function add(mixed $element)
323 {
324 $this->elements[] = $element;
325 }
326
327 /**
328 * {@inheritDoc}
329 */
330 public function isEmpty()
331 {
332 return empty($this->elements);
333 }
334
335 /**
336 * {@inheritDoc}
337 *
338 * @return Traversable<int|string, mixed>
339 * @phpstan-return Traversable<TKey, T>
340 */
341 #[ReturnTypeWillChange]
342 public function getIterator()
343 {
344 return new ArrayIterator($this->elements);
345 }
346
347 /**
348 * {@inheritDoc}
349 *
350 * @phpstan-param Closure(T):U $func
351 *
352 * @return static
353 * @phpstan-return static<TKey, U>
354 *
355 * @phpstan-template U
356 */
357 public function map(Closure $func)
358 {
359 return $this->createFrom(array_map($func, $this->elements));
360 }
361
362 /**
363 * {@inheritDoc}
364 */
365 public function reduce(Closure $func, $initial = null)
366 {
367 return array_reduce($this->elements, $func, $initial);
368 }
369
370 /**
371 * {@inheritDoc}
372 *
373 * @phpstan-param Closure(T, TKey):bool $p
374 *
375 * @return static
376 * @phpstan-return static<TKey,T>
377 */
378 public function filter(Closure $p)
379 {
380 return $this->createFrom(array_filter($this->elements, $p, ARRAY_FILTER_USE_BOTH));
381 }
382
383 /**
384 * {@inheritDoc}
385 */
386 public function findFirst(Closure $p)
387 {
388 return array_find(
389 $this->elements,
390 static fn (mixed $element, mixed $key): bool => (bool) $p($key, $element),
391 );
392 }
393
394 /**
395 * {@inheritDoc}
396 */
397 public function forAll(Closure $p)
398 {
399 return array_all(
400 $this->elements,
401 static fn (mixed $element, mixed $key): bool => (bool) $p($key, $element),
402 );
403 }
404
405 /**
406 * {@inheritDoc}
407 */
408 public function partition(Closure $p)
409 {
410 $matches = $noMatches = [];
411
412 foreach ($this->elements as $key => $element) {
413 if ($p($key, $element)) {
414 $matches[$key] = $element;
415 } else {
416 $noMatches[$key] = $element;
417 }
418 }
419
420 return [$this->createFrom($matches), $this->createFrom($noMatches)];
421 }
422
423 /**
424 * Returns a string representation of this object.
425 * {@inheritDoc}
426 *
427 * @return string
428 */
429 #[ReturnTypeWillChange]
430 public function __toString()
431 {
432 return self::class . '@' . spl_object_hash($this);
433 }
434
435 /**
436 * {@inheritDoc}
437 */
438 public function clear()
439 {
440 $this->elements = [];
441 }
442
443 /**
444 * {@inheritDoc}
445 */
446 public function slice(int $offset, int|null $length = null)
447 {
448 return array_slice($this->elements, $offset, $length, true);
449 }
450
451 /** @phpstan-return Collection<TKey, T>&Selectable<TKey,T> */
452 public function matching(Criteria $criteria)
453 {
454 $accessRawFieldValues = $criteria->isRawFieldValueAccessEnabled();
455
456 $expr = $criteria->getWhereExpression();
457 $filtered = $this->elements;
458
459 if ($expr) {
460 $visitor = new ClosureExpressionVisitor($accessRawFieldValues);
461 $filter = $visitor->dispatch($expr);
462 $filtered = array_filter($filtered, $filter);
463 }
464
465 $orderings = $criteria->orderings();
466
467 if ($orderings) {
468 $next = null;
469 foreach (array_reverse($orderings) as $field => $ordering) {
470 $next = ClosureExpressionVisitor::sortByField($field, $ordering === Order::Descending ? -1 : 1, $next, $accessRawFieldValues);
471 }
472
473 uasort($filtered, $next);
474 }
475
476 $offset = $criteria->getFirstResult();
477 $length = $criteria->getMaxResults();
478
479 if ($offset !== null && $offset > 0 || $length !== null && $length > 0) {
480 $filtered = array_slice($filtered, (int) $offset, $length, true);
481 }
482
483 return $this->createFrom($filtered);
484 }
485 }