vendor/doctrine/collections/src/ArrayCollection.php line 49

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