fix: address code review findings

- Add JsonSerializable support via jsonSerialize() in trait
- Cache ReflectionEnum in EnumValidationRule constructor
- Bump minimum PHP to 8.2 (Pest v3 requirement)
- Add IteratorAggregate to EnumCollection for foreach support
- Narrow PHPStan return.type ignore to inline comment
- Add tests for jsonSerialize and foreach iteration

Author: ndcorder

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.1', '8.2', '8.3', '8.4']
+        php: ['8.2', '8.3', '8.4']
 
     name: PHP ${{ matrix.php }}
 

README.md

@@ -13,7 +13,7 @@ PHP 8.1 introduced native enums, but the ecosystem still relies on `myclabs/php-
 composer require kexxt/enum-utils
 ```
 
-Requires PHP 8.1+.
+Requires PHP 8.2+.
 
 ## Quick Start
 

composer.json

@@ -5,7 +5,7 @@
     "license": "MIT",
     "minimum-stability": "stable",
     "require": {
-        "php": "^8.1"
+        "php": "^8.2"
     },
     "require-dev": {
         "pestphp/pest": "^3.0",

phpstan.neon

@@ -7,5 +7,3 @@ parameters:
     ignoreErrors:
         - identifier: function.alreadyNarrowedType
         - identifier: function.impossibleType
-        - identifier: return.type
-          path: src/EnumUtilsTrait.php

src/EnumCollection.php

@@ -6,8 +6,9 @@
 
 /**
  * @template T of \BackedEnum
+ * @implements \IteratorAggregate<int, T>
  */
-class EnumCollection implements \Countable
+class EnumCollection implements \Countable, \IteratorAggregate
 {
     /** @var list<T> */
     private array $cases;
@@ -94,4 +95,12 @@ public function count(): int
     {
         return count($this->cases);
     }
+
+    /**
+     * @return \ArrayIterator<int, T>
+     */
+    public function getIterator(): \ArrayIterator
+    {
+        return new \ArrayIterator($this->cases);
+    }
 }

src/EnumUtilsTrait.php

@@ -112,12 +112,21 @@ public static function randomCase(): static
 
     /**
      * Get the backing value for JSON serialization.
+     * Implements JsonSerializable when the enum declares it.
      */
     public function toJsonValue(): string|int
     {
         return $this->value;
     }
 
+    /**
+     * JsonSerializable implementation.
+     */
+    public function jsonSerialize(): string|int
+    {
+        return $this->value;
+    }
+
     /**
      * Create a case from a JSON value.
      */
@@ -133,7 +142,7 @@ public static function fromJsonValue(string|int $value): static
      */
     public static function collect(): EnumCollection
     {
-        return new EnumCollection(self::cases());
+        return new EnumCollection(self::cases()); // @phpstan-ignore return.type
     }
 
     /**

src/Validation/EnumValidationRule.php

@@ -9,6 +9,8 @@ class EnumValidationRule
     /** @var class-string<\BackedEnum> */
     private string $enumClass;
 
+    private string $backingTypeName;
+
     /**
      * @param class-string<\BackedEnum> $enumClass
      */
@@ -21,6 +23,10 @@ public function __construct(string $enumClass)
         }
 
         $this->enumClass = $enumClass;
+
+        $reflection = new \ReflectionEnum($enumClass);
+        $backingType = $reflection->getBackingType();
+        $this->backingTypeName = $backingType !== null ? $backingType->getName() : 'string';
     }
 
     /**
@@ -40,17 +46,11 @@ public function validate(mixed $value): bool
             return false;
         }
 
-        $reflection = new \ReflectionEnum($this->enumClass);
-        $backingType = $reflection->getBackingType();
-
-        if ($backingType !== null) {
-            $typeName = $backingType->getName();
-            if ($typeName === 'string' && !is_string($value)) {
-                return false;
-            }
-            if ($typeName === 'int' && !is_int($value)) {
-                return false;
-            }
+        if ($this->backingTypeName === 'string' && !is_string($value)) {
+            return false;
+        }
+        if ($this->backingTypeName === 'int' && !is_int($value)) {
+            return false;
         }
 
         return $this->enumClass::tryFrom($value) !== null;

tests/EnumCollectionTest.php

@@ -54,3 +54,12 @@
     expect($collection->count())->toBe(0);
     expect(count($collection))->toBe(0);
 });
+
+test('collection is iterable with foreach', function () {
+    $collection = new EnumCollection([Priority::Low, Priority::High]);
+    $result = [];
+    foreach ($collection as $case) {
+        $result[] = $case;
+    }
+    expect($result)->toBe([Priority::Low, Priority::High]);
+});

tests/EnumUtilsTraitTest.php

@@ -109,6 +109,17 @@
         ->toThrow(ValueError::class);
 });
 
+// jsonSerialize()
+test('jsonSerialize returns the backing value', function () {
+    expect(Status::Active->jsonSerialize())->toBe('active');
+    expect(Priority::High->jsonSerialize())->toBe(3);
+});
+
+test('json_encode uses jsonSerialize', function () {
+    expect(json_encode(Status::Active))->toBe('"active"');
+    expect(json_encode(Priority::High))->toBe('3');
+});
+
 // collect()
 test('collect returns an EnumCollection', function () {
     $collection = Status::collect();

tests/Fixtures/Priority.php

@@ -6,7 +6,7 @@
 
 use Kexxt\EnumUtils\EnumUtilsTrait;
 
-enum Priority: int
+enum Priority: int implements \JsonSerializable
 {
     use EnumUtilsTrait;