Add testing utils

src/Data/Collection.php

@@ -4,22 +4,35 @@
 
 namespace Phenix\Data;
 
+use Closure;
 use Phenix\Contracts\Arrayable;
 use Ramsey\Collection\Collection as GenericCollection;
-use SplFixedArray;
+use Ramsey\Collection\CollectionInterface;
+use Ramsey\Collection\Exception\CollectionMismatchException;
+use Ramsey\Collection\Sort;
 
+use function array_filter;
 use function array_key_first;
+use function array_map;
+use function array_merge;
+use function array_udiff;
+use function array_uintersect;
+use function is_int;
+use function is_object;
+use function spl_object_id;
+use function sprintf;
+use function usort;
 
+/**
+ * @template T
+ * @extends GenericCollection<T>
+ */
 class Collection extends GenericCollection implements Arrayable
 {
     public static function fromArray(array $data): self
     {
-        $data = SplFixedArray::fromArray($data);
-        $collection = new self('array');
-
-        foreach ($data as $value) {
-            $collection->add($value);
-        }
+        $collection = new self(self::getDataType($data));
+        $collection->data = $data;
 
         return $collection;
     }
@@ -34,4 +47,207 @@ public function first(): mixed
 
         return $this->data[$firstIndex];
     }
+
+    /**
+     * @param callable(T): bool $callback
+     *
+     * @return self<T>
+     */
+    public function filter(callable $callback): self
+    {
+        $collection = clone $this;
+        $collection->data = array_merge([], array_filter($collection->data, $callback));
+
+        return $collection;
+    }
+
+    /**
+     * @param callable(T): TCallbackReturn $callback
+     *
+     * @return self<TCallbackReturn>
+     *
+     * @template TCallbackReturn
+     */
+    public function map(callable $callback): self
+    {
+        return new self('mixed', array_map($callback, $this->data));
+    }
+
+    /**
+     * @param string|null $propertyOrMethod
+     * @param mixed $value
+     *
+     * @return self<T>
+     */
+    public function where(string|null $propertyOrMethod, mixed $value): self
+    {
+        return $this->filter(
+            fn (mixed $item): bool => $this->extractValue($item, $propertyOrMethod) === $value,
+        );
+    }
+
+    /**
+     * @param string|null $propertyOrMethod
+     * @param Sort $order
+     *
+     * @return self<T>
+     */
+    public function sort(string|null $propertyOrMethod = null, Sort $order = Sort::Ascending): self
+    {
+        $collection = clone $this;
+
+        usort(
+            $collection->data,
+            function (mixed $a, mixed $b) use ($propertyOrMethod, $order): int {
+                $aValue = $this->extractValue($a, $propertyOrMethod);
+                $bValue = $this->extractValue($b, $propertyOrMethod);
+
+                return ($aValue <=> $bValue) * ($order === Sort::Descending ? -1 : 1);
+            },
+        );
+
+        return $collection;
+    }
+
+    /**
+     * @param CollectionInterface<T> $other
+     *
+     * @return self<T>
+     */
+    public function diff(CollectionInterface $other): self
+    {
+        $this->compareCollectionTypes($other);
+
+        $diffAtoB = array_udiff($this->data, $other->toArray(), $this->getComparator());
+        $diffBtoA = array_udiff($other->toArray(), $this->data, $this->getComparator());
+
+        $collection = clone $this;
+        $collection->data = array_merge($diffAtoB, $diffBtoA);
+
+        return $collection;
+    }
+
+    /**
+     * @param CollectionInterface<T> $other
+     *
+     * @return self<T>
+     */
+    public function intersect(CollectionInterface $other): self
+    {
+        $this->compareCollectionTypes($other);
+
+        $collection = clone $this;
+        $collection->data = array_uintersect($this->data, $other->toArray(), $this->getComparator());
+
+        return $collection;
+    }
+
+    /**
+     * @param CollectionInterface<T> ...$collections
+     *
+     * @return self<T>
+     */
+    public function merge(CollectionInterface ...$collections): self
+    {
+        $mergedCollection = clone $this;
+
+        foreach ($collections as $index => $collection) {
+            if (! $collection instanceof static) {
+                throw new CollectionMismatchException(
+                    sprintf('Collection with index %d must be of type %s', $index, static::class),
+                );
+            }
+
+            if ($this->getUniformType($collection) !== $this->getUniformType($this)) {
+                throw new CollectionMismatchException(
+                    sprintf(
+                        'Collection items in collection with index %d must be of type %s',
+                        $index,
+                        $this->getType(),
+                    ),
+                );
+            }
+
+            foreach ($collection as $key => $value) {
+                if (is_int($key)) {
+                    $mergedCollection[] = $value;
+                } else {
+                    $mergedCollection[$key] = $value;
+                }
+            }
+        }
+
+        return $mergedCollection;
+    }
+
+    /**
+     * @param CollectionInterface<T> $other
+     *
+     * @throws CollectionMismatchException
+     */
+    private function compareCollectionTypes(CollectionInterface $other): void
+    {
+        if (! $other instanceof static) {
+            throw new CollectionMismatchException('Collection must be of type ' . static::class);
+        }
+
+        if ($this->getUniformType($other) !== $this->getUniformType($this)) {
+            throw new CollectionMismatchException('Collection items must be of type ' . $this->getType());
+        }
+    }
+
+    private function getComparator(): Closure
+    {
+        return function (mixed $a, mixed $b): int {
+            if (is_object($a) && is_object($b)) {
+                $a = spl_object_id($a);
+                $b = spl_object_id($b);
+            }
+
+            if ($a === $b) {
+                return 0;
+            }
+
+            if ($a < $b) {
+                return 1;
+            }
+
+            return -1;
+        };
+    }
+
+    /**
+     * @param CollectionInterface<mixed> $collection
+     */
+    private function getUniformType(CollectionInterface $collection): string
+    {
+        return match ($collection->getType()) {
+            'integer' => 'int',
+            'boolean' => 'bool',
+            'double' => 'float',
+            default => $collection->getType(),
+        };
+    }
+
+    /**
+     * @param array<mixed> $data
+     *
+     * @return string
+     */
+    private static function getDataType(array $data): string
+    {
+        if (empty($data)) {
+            return 'mixed';
+        }
+
+        $firstType = gettype(reset($data));
+
+        foreach ($data as $item) {
+            if (gettype($item) !== $firstType) {
+                return 'mixed';
+            }
+        }
+
+        return $firstType;
+    }
 }

src/Database/Models/QueryBuilders/DatabaseQueryBuilder.php

@@ -139,7 +139,7 @@ public function with(array|string $relationships): self
     }
 
     /**
-     * @return Collection<int, DatabaseModel>
+     * @return Collection<DatabaseModel>
      */
     public function get(): Collection
     {
@@ -215,7 +215,7 @@ protected function resolveRelationships(Collection $collection): void
     }
 
     /**
-     * @param Collection<int, DatabaseModel> $models
+     * @param Collection<DatabaseModel> $models
      * @param BelongsTo $relationship
      * @param Closure $closure
      */
@@ -226,7 +226,7 @@ protected function resolveBelongsToRelationship(
     ): void {
         $closure($relationship);
 
-        /** @var Collection<int, DatabaseModel> $records */
+        /** @var Collection<DatabaseModel> $records */
         $records = $relationship->query()
             ->whereIn($relationship->getForeignKey()->getColumnName(), $models->modelKeys())
             ->get();
@@ -243,7 +243,7 @@ protected function resolveBelongsToRelationship(
     }
 
     /**
-     * @param Collection<int, DatabaseModel> $models
+     * @param Collection<DatabaseModel> $models
      * @param HasMany $relationship
      * @param Closure $closure
      */
@@ -254,7 +254,7 @@ protected function resolveHasManyRelationship(
     ): void {
         $closure($relationship);
 
-        /** @var Collection<int, DatabaseModel> $children */
+        /** @var Collection<DatabaseModel> $children */
         $children = $relationship->query()
             ->whereIn($relationship->getProperty()->getAttribute()->foreignKey, $models->modelKeys())
             ->get();
@@ -284,7 +284,7 @@ protected function resolveHasManyRelationship(
     }
 
     /**
-     * @param Collection<int, DatabaseModel> $models
+     * @param Collection<DatabaseModel> $models
      * @param BelongsToMany $relationship
      * @param Closure $closure
      */
@@ -297,7 +297,7 @@ protected function resolveBelongsToManyRelationship(
 
         $attr = $relationship->getProperty()->getAttribute();
 
-        /** @var Collection<int, DatabaseModel> $related */
+        /** @var Collection<DatabaseModel> $related */
         $related = $relationship->query()
             ->addSelect($relationship->getColumns())
             ->innerJoin($attr->table, function (Join $join) use ($attr): void {

src/Database/QueryBuilder.php

@@ -68,7 +68,7 @@ public function connection(SqlCommonConnectionPool|string $connection): self
     }
 
     /**
-     * @return Collection<int, array>
+     * @return Collection<array<string, mixed>>
      */
     public function get(): Collection
     {