fix: EnumCaster Backed Typing (#9)

Author: ALameLlama

src/Attributes/CastWith.php

@@ -11,6 +11,7 @@
 
 use function array_key_exists;
 use function is_array;
+use function is_null;
 
 #[Attribute(Attribute::TARGET_PROPERTY)]
 /**
@@ -43,6 +44,11 @@ public function handle(string $propertyName, array &$data): void
 
         $value = $data[$propertyName];
 
+        // If it's null return early
+        if (is_null($value)) {
+            return;
+        }
+
         // If using a CasterInterface implementation
         if ($this->caster instanceof CasterInterface) {
             $data[$propertyName] = $this->caster->cast($value);

src/Casters/EnumCaster.php

@@ -7,6 +7,7 @@
 use Alamellama\Carapace\Contracts\CasterInterface;
 use BackedEnum;
 use InvalidArgumentException;
+use ReflectionEnum;
 use UnitEnum;
 use ValueError;
 
@@ -39,21 +40,21 @@ public function __construct(
      */
     public function cast(mixed $value): UnitEnum
     {
-        // If already an instance of the target enum, return it
         if ($value instanceof $this->enumClass && $value instanceof UnitEnum) {
             return $value;
         }
 
-        // Check if the enum class exists
         if (! enum_exists($this->enumClass)) {
             throw new InvalidArgumentException("Invalid enum class: {$this->enumClass}");
         }
 
-        // Handle backed enums
         if (is_subclass_of($this->enumClass, BackedEnum::class)) {
-            // Try to get the enum case from its value
             try {
-                /** @var int|string $value */
+                $reflectedEnum = new ReflectionEnum($this->enumClass);
+
+                // @phpstan-ignore-next-line
+                $value = $reflectedEnum->getBackingType()?->getName() === 'int' ? (int) $value : (string) $value;
+
                 return $this->enumClass::from($value);
             } catch (ValueError $e) {
                 // If the exact value doesn't exist, try to find a case that matches case-insensitively
@@ -64,15 +65,12 @@ public function cast(mixed $value): UnitEnum
                         }
                     }
                 }
-
                 // Use tryFrom as a fallback
-                if ($value !== null) {
-                    $result = $this->enumClass::tryFrom($value);
-                    if ($result !== null) {
-                        // @codeCoverageIgnoreStart
-                        return $result;
-                        // @codeCoverageIgnoreEnd
-                    }
+                $result = $this->enumClass::tryFrom($value);
+                if ($result !== null) {
+                    // @codeCoverageIgnoreStart
+                    return $result;
+                    // @codeCoverageIgnoreEnd
                 }
 
                 throw new InvalidArgumentException(
@@ -83,7 +81,6 @@ public function cast(mixed $value): UnitEnum
             }
         }
 
-        // Handle unit enums (enums without values)
         // For unit enums, we need to match by name
         if (is_string($value)) {
             foreach ($this->enumClass::cases() as $case) {

tests/Fixtures/Enums/StatusCode.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures\Enums;
+
+enum StatusCode: int
+{
+    case PENDING = 100;
+    case ACTIVE = 200;
+    case INACTIVE = 300;
+}

tests/Unit/EnumCasterTest.php

@@ -10,54 +10,96 @@
 use InvalidArgumentException;
 use Tests\Fixtures\Enums\Color;
 use Tests\Fixtures\Enums\Status;
+use Tests\Fixtures\Enums\StatusCode;
 
-final class WithEnumCasting extends ImmutableDTO
+final class StatusDto extends ImmutableDTO
 {
     public function __construct(
         #[CastWith(new EnumCaster(Status::class))]
         public Status $status,
+    ) {}
+}
 
+final class ColorDto extends ImmutableDTO
+{
+    public function __construct(
         #[CastWith(new EnumCaster(Color::class))]
-        public Color $color
+        public Color $color,
+    ) {}
+}
+
+final class StatusCodeDto extends ImmutableDTO
+{
+    public function __construct(
+        #[CastWith(new EnumCaster(StatusCode::class))]
+        public StatusCode $statusCode,
+    ) {}
+}
+
+final class CombinedDto extends ImmutableDTO
+{
+    public function __construct(
+        #[CastWith(new EnumCaster(Status::class))]
+        public Status $status,
+
+        #[CastWith(new EnumCaster(StatusCode::class))]
+        public ?StatusCode $statusCode,
     ) {}
 }
 
 it('can cast string to backed enum using exact value', function (): void {
-    $dto = WithEnumCasting::from([
+    $dto = StatusDto::from([
         'status' => 'active',
-        'color' => 'RED',
     ]);
 
     expect($dto->status)
-        ->toBe(Status::ACTIVE)
-        ->and($dto->color)
-        ->toBe(Color::RED);
+        ->toBe(Status::ACTIVE);
 });
 
 it('can cast string to backed enum using case-insensitive value', function (): void {
-    $dto = WithEnumCasting::from([
+    $dto = StatusDto::from([
         'status' => 'ACTIVE',
-        'color' => 'RED',
     ]);
 
     expect($dto->status)
         ->toBe(Status::ACTIVE);
 });
 
+it('can cast int backed enum using int value', function (): void {
+    $dto = StatusCodeDto::from([
+        'statusCode' => 100,
+    ]);
+
+    expect($dto->statusCode)
+        ->toBe(StatusCode::PENDING);
+});
+
+it('can cast int backed enum using string value', function (): void {
+    $dto = StatusCodeDto::from([
+        'statusCode' => '300',
+    ]);
+
+    expect($dto->statusCode)
+        ->toBe(StatusCode::INACTIVE);
+});
+
 it('can handle existing enum instances', function (): void {
-    $dto = WithEnumCasting::from([
+    $dto1 = StatusDto::from([
         'status' => Status::PENDING,
+    ]);
+
+    $dto2 = ColorDto::from([
         'color' => Color::GREEN,
     ]);
 
-    expect($dto->status)
+    expect($dto1->status)
         ->toBe(Status::PENDING)
-        ->and($dto->color)
+        ->and($dto2->color)
         ->toBe(Color::GREEN);
 });
 
 it('can cast string to unit enum using case name', function (): void {
-    $dto = WithEnumCasting::from([
+    $dto = ColorDto::from([
         'status' => 'active',
         'color' => 'BLUE',
     ]);
@@ -67,8 +109,7 @@ public function __construct(
 });
 
 it('can cast string to unit enum using case-insensitive name', function (): void {
-    $dto = WithEnumCasting::from([
-        'status' => 'active',
+    $dto = ColorDto::from([
         'color' => 'blue',
     ]);
 
@@ -77,15 +118,13 @@ public function __construct(
 });
 
 it('throws exception for invalid backed enum value', function (): void {
-    WithEnumCasting::from([
+    StatusDto::from([
         'status' => 'unknown',
-        'color' => 'RED',
     ]);
 })->throws(InvalidArgumentException::class, 'Cannot cast value to enum Tests\Fixtures\Enums\Status');
 
 it('throws exception for invalid unit enum name', function (): void {
-    WithEnumCasting::from([
-        'status' => 'active',
+    ColorDto::from([
         'color' => 'YELLOW',
     ]);
 })->throws(InvalidArgumentException::class, 'Cannot cast value to enum Tests\Fixtures\Enums\Color: no matching case found');
@@ -99,3 +138,28 @@ public function __construct(
     $caster = new EnumCaster(Color::class);
     $caster->cast(123);
 })->throws(InvalidArgumentException::class, 'Cannot cast value to enum Tests\Fixtures\Enums\Color: no matching case found');
+
+it('can handle optional property', function (): void {
+    $dto = CombinedDto::from([
+        'status' => Status::PENDING,
+    ]);
+
+    expect($dto->status)
+        ->toBe(Status::PENDING);
+
+    expect($dto->statusCode)
+        ->toBeNull();
+});
+
+it('can handle null property', function (): void {
+    $dto = CombinedDto::from([
+        'status' => Status::PENDING,
+        'statusCode' => null,
+    ]);
+
+    expect($dto->status)
+        ->toBe(Status::PENDING);
+
+    expect($dto->statusCode)
+        ->toBeNull();
+});