[EasyUtils] Improve CollectorHelper

packages/EasyErrorHandler/src/Bridge/Laravel/config/easy-error-handler.php

@@ -7,7 +7,7 @@
      * Use extended error response with exception message, trace, etc.
      */
     'use_extended_response' => \env('EASY_ERROR_HANDLER_USE_EXTENDED_RESPONSE', false),
-    
+
     /**
      * Use default set of error response builders.
      */

packages/EasyErrorHandler/src/Traits/DealsWithErrorLogLevelTrait.php

@@ -1,4 +1,5 @@
 <?php
+
 declare(strict_types=1);
 
 namespace EonX\EasyErrorHandler\Traits;

packages/EasyUtils/readme.md

@@ -132,7 +132,7 @@ final class MyClass
     public function __construct(iterable $workers)
     {
         // $workers now contains only WorkerInterface instances
-        $workers = CollectorHelper::filterByClass(WorkerInterface::class, $workers);
+        $workers = CollectorHelper::filterByClass($workers, WorkerInterface::class);
 
         // The filterByClass() method still returns an iterable, a generator more precisely
         // If you need an array, you can use the filterByClassAsArray() method
@@ -169,14 +169,49 @@ final class MyClass
     public function __construct(iterable $workers)
     {
         // $workers now contains only WorkerInterface instances
-        $workers = CollectorHelper::filterByClassAsArray(WorkerInterface::class, $workers);
+        $workers = CollectorHelper::filterByClassAsArray($workers, WorkerInterface::class);
 
         // $workers is now an array containing only WorkerInterface instances
         $this->workers = $workers;
     }
 }
 ```
 
+### CollectorHelper::ensureClass() and CollectorHelper::ensureClassAsArray()
+
+Those methods are similar to the `filterByClass()` and `filterByClassAsArray()` methods, however they will throw an
+exception if at least of the items is not an instance of the given class.
+
+```php
+use App\Domain\WorkerInterface;
+use EonX\EasyUtils\CollectorHelper;
+
+final class MyClass
+{
+    /**
+     * @var \App\Domain\WorkerInterface[]
+     */
+    private array $workers;
+
+    /**
+     * @param iterable<mixed> $workers
+     */
+    public function __construct(iterable $workers)
+    {
+        // $workers now contains only WorkerInterface instances
+        $workers = CollectorHelper::ensureClass(WorkerInterface::class, $workers);
+
+        foreach ($workers as $worker) {
+            // This code will be executed only if all items are instances of WorkerInterface
+        }
+    }
+}
+```
+
+::: warning
+Please note that with the `ensureClass()` method, the exception will be thrown only when iterating through the generator.
+:::
+
 ### CollectorHelper::orderHigherPriorityFirst()
 
 The `orderHigherPriorityFirst()` method will ensure the object with the highest priority is placed first, and the object
@@ -198,6 +233,11 @@ $objects = [$foo, $bar];
 $objects = CollectorHelper::orderHigherPriorityFirst($objects); // [$bar, $foo]
 ```
 
+::: tip
+The `orderHigherPriorityFirst()` method still returns an iterable (or, more precisely, a generator). If you need an `array`, you
+can use the `orderHigherPriorityFirstAsArray()` method instead.
+:::
+
 ### CollectorHelper::orderLowerPriorityFirst()
 
 The `orderLowerPriorityFirst()` method is the opposite of `orderHigherPriorityFirst()`. It will ensure the object with
@@ -219,6 +259,11 @@ $objects = [$foo, $bar];
 $objects = CollectorHelper::orderLowerPriorityFirst($objects); // [$foo, $bar]
 ```
 
+::: tip
+The `orderLowerPriorityFirst()` method still returns an iterable (or, more precisely, a generator). If you need an `array`, you
+can use the `orderLowerPriorityFirstAsArray()` method instead.
+:::
+
 [1]: https://getcomposer.org/
 [2]: https://tomasvotruba.com/blog/2018/06/14/collector-pattern-for-dummies/
 [3]: https://book.cakephp.org/4.next/en/development/dependency-injection.html#tagging-services

packages/EasyUtils/src/CollectorHelper.php

@@ -4,6 +4,7 @@
 
 namespace EonX\EasyUtils;
 
+use EonX\EasyUtils\Exceptions\InvalidArgumentException;
 use EonX\EasyUtils\Interfaces\HasPriorityInterface;
 
 final class CollectorHelper
@@ -18,10 +19,44 @@ public static function convertToArray(iterable $items): array
         return $items instanceof \Traversable ? \iterator_to_array($items) : (array)$items;
     }
 
+    /**
+     * @param iterable<mixed> $items
+     *
+     * @return iterable<mixed>
+     *
+     * @throws \EonX\EasyUtils\Exceptions\InvalidArgumentException
+     */
+    public static function ensureClass(iterable $items, string $class): iterable
+    {
+        foreach ($items as $item) {
+            if (($item instanceof $class) === false) {
+                throw new InvalidArgumentException(\sprintf(
+                    'Instance of %s expected, %s given',
+                    $class,
+                    \is_object($item) === false ? \gettype($item) : \get_class($item)
+                ));
+            }
+
+            yield $item;
+        }
+    }
+
     /**
      * @param iterable<mixed> $items
      *
      * @return mixed[]
+     *
+     * @throws \EonX\EasyUtils\Exceptions\InvalidArgumentException
+     */
+    public static function ensureClassAsArray(iterable $items, string $class): array
+    {
+        return self::convertToArray(self::ensureClass($items, $class));
+    }
+
+    /**
+     * @param iterable<mixed> $items
+     *
+     * @return iterable<mixed>
      */
     public static function filterByClass(iterable $items, string $class): iterable
     {
@@ -44,11 +79,11 @@ public static function filterByClassAsArray(iterable $items, string $class): arr
     }
 
     /**
-     * @param mixed[] $items
+     * @param iterable<mixed> $items
      *
-     * @return mixed[]
+     * @return iterable<mixed>
      */
-    public static function orderHigherPriorityFirst(iterable $items): array
+    public static function orderHigherPriorityFirst(iterable $items): iterable
     {
         $items = self::convertToArray($items);
 
@@ -59,15 +94,27 @@ public static function orderHigherPriorityFirst(iterable $items): array
             return $secondPriority <=> $firstPriority;
         });
 
-        return $items;
+        foreach ($items as $item) {
+            yield $item;
+        }
     }
 
     /**
-     * @param mixed[] $items
+     * @param iterable<mixed> $items
      *
      * @return mixed[]
      */
-    public static function orderLowerPriorityFirst(iterable $items): array
+    public static function orderHigherPriorityFirstAsArray(iterable $items): array
+    {
+        return self::convertToArray(self::orderHigherPriorityFirst($items));
+    }
+
+    /**
+     * @param iterable<mixed> $items
+     *
+     * @return iterable<mixed>
+     */
+    public static function orderLowerPriorityFirst(iterable $items): iterable
     {
         $items = self::convertToArray($items);
 
@@ -78,6 +125,18 @@ public static function orderLowerPriorityFirst(iterable $items): array
             return $firstPriority <=> $secondPriority;
         });
 
-        return $items;
+        foreach ($items as $item) {
+            yield $item;
+        }
+    }
+
+    /**
+     * @param iterable<mixed> $items
+     *
+     * @return mixed[]
+     */
+    public static function orderLowerPriorityFirstAsArray(iterable $items): array
+    {
+        return self::convertToArray(self::orderLowerPriorityFirst($items));
     }
 }

packages/EasyUtils/src/Exceptions/InvalidArgumentException.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EonX\EasyUtils\Exceptions;
+
+use EonX\EasyUtils\Interfaces\EasyUtilsExceptionInterface;
+
+final class InvalidArgumentException extends \InvalidArgumentException implements EasyUtilsExceptionInterface
+{
+    // No body needed.
+}

packages/EasyUtils/src/Interfaces/EasyUtilsExceptionInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EonX\EasyUtils\Interfaces;
+
+interface EasyUtilsExceptionInterface
+{
+    // Marker for all exceptions of this package.
+}

packages/EasyUtils/tests/CollectorHelperTest.php

@@ -5,10 +5,23 @@
 namespace EonX\EasyUtils\Tests;
 
 use EonX\EasyUtils\CollectorHelper;
+use EonX\EasyUtils\Exceptions\InvalidArgumentException;
 use EonX\EasyUtils\Tests\Stubs\HasPriorityStub;
 
 final class CollectorHelperTest extends AbstractTestCase
 {
+    /**
+     * @return iterable<mixed>
+     */
+    public function providerTestEnsureClass(): iterable
+    {
+        yield 'basic type' => [[0], true];
+
+        yield 'basic object' => [[new \stdClass()], false];
+
+        yield 'interface based' => [[new HasPriorityStub(), new \stdClass()], true];
+    }
+
     /**
      * @return iterable<mixed>
      *
@@ -63,6 +76,24 @@ public function providerTestOrderLowerPriorityFirst(): iterable
         yield 'same order when no priority' => [[$noPriority1, $noPriority2], [$noPriority1, $noPriority2]];
     }
 
+    /**
+     * @param iterable<mixed> $items
+     *
+     * @dataProvider providerTestEnsureClass
+     */
+    public function testEnsureClass(iterable $items, bool $expectException, ?string $class = null): void
+    {
+        if ($expectException) {
+            $this->expectException(InvalidArgumentException::class);
+        }
+
+        // Convert to array so it goes through the generator
+        CollectorHelper::ensureClassAsArray($items, $class ?? \stdClass::class);
+
+        // If it reaches here, test is valid
+        self::assertTrue(true);
+    }
+
     /**
      * @param iterable<mixed> $items
      * @param null|class-string $class
@@ -89,7 +120,7 @@ public function testFilterByClass(iterable $items, int $expectedCount, ?string $
      */
     public function testOrderHigherPriorityFirst(iterable $items, array $expected): void
     {
-        self::assertEquals($expected, CollectorHelper::orderHigherPriorityFirst($items));
+        self::assertEquals($expected, CollectorHelper::orderHigherPriorityFirstAsArray($items));
     }
 
     /**
@@ -100,7 +131,7 @@ public function testOrderHigherPriorityFirst(iterable $items, array $expected):
      */
     public function testOrderLowerPriorityFirst(iterable $items, array $expected): void
     {
-        self::assertEquals($expected, CollectorHelper::orderLowerPriorityFirst($items));
+        self::assertEquals($expected, CollectorHelper::orderLowerPriorityFirstAsArray($items));
     }
 
     private function hasPriorityStub(?int $priority = null): HasPriorityStub