fix: populate enum-typed properties with enum instances

Author: stainless-app[bot]

src/Core/Conversion/EnumOf.php

@@ -19,9 +19,12 @@ final class EnumOf implements Converter
 
     /**
      * @param list<bool|float|int|string|null> $members
+     * @param class-string<\BackedEnum>|null   $class
      */
-    public function __construct(private readonly array $members)
-    {
+    public function __construct(
+        private readonly array $members,
+        private readonly ?string $class = null,
+    ) {
         $type = 'NULL';
         foreach ($this->members as $member) {
             $type = gettype($member);
@@ -33,13 +36,24 @@ public function __construct(private readonly array $members)
     public static function fromBackedEnum(string $enum): self
     {
         // @phpstan-ignore-next-line argument.type
-        return self::$cache[$enum] ??= new self(array_column($enum::cases(), column_key: 'value'));
+        return self::$cache[$enum] ??= new self(
+            array_column($enum::cases(), column_key: 'value'),
+            class: $enum,
+        );
     }
 
     public function coerce(mixed $value, CoerceState $state): mixed
     {
         $this->tally($value, state: $state);
 
+        if ($value instanceof \BackedEnum) {
+            return $value;
+        }
+
+        if (null !== $this->class && (is_int($value) || is_string($value))) {
+            return ($this->class)::tryFrom($value) ?? $value;
+        }
+
         return $value;
     }
 

tests/Core/ModelTest.php

@@ -47,6 +47,30 @@ public function __construct(
     }
 }
 
+enum TicketPriority: string
+{
+    case Low = 'low';
+    case High = 'high';
+}
+
+class Ticket implements BaseModel
+{
+    /** @use SdkModel<array<string, mixed>> */
+    use SdkModel;
+
+    #[Required(enum: TicketPriority::class)]
+    public TicketPriority $priority;
+
+    /** @var list<TicketPriority> */
+    #[Required(list: TicketPriority::class)]
+    public array $labels;
+
+    public function __construct()
+    {
+        $this->initialize();
+    }
+}
+
 /**
  * @internal
  *
@@ -141,4 +165,42 @@ public function testSerializeModelWithExplicitNull(): void
             json_encode($model)
         );
     }
+
+    #[Test]
+    public function testScalarEnumCoercesToInstance(): void
+    {
+        $model = Ticket::fromArray(['priority' => 'low', 'labels' => []]);
+        $this->assertSame(TicketPriority::Low, $model->priority);
+    }
+
+    #[Test]
+    public function testListOfEnumCoercesElementsToInstances(): void
+    {
+        $model = Ticket::fromArray(['priority' => 'low', 'labels' => ['low', 'high']]);
+        $this->assertCount(2, $model->labels);
+        $this->assertSame(TicketPriority::Low, $model->labels[0]);
+        $this->assertSame(TicketPriority::High, $model->labels[1]);
+    }
+
+    #[Test]
+    public function testEnumInstancePassesThrough(): void
+    {
+        $model = Ticket::fromArray(['priority' => TicketPriority::High, 'labels' => []]);
+        $this->assertSame(TicketPriority::High, $model->priority);
+    }
+
+    #[Test]
+    public function testInvalidEnumScalarFallsBackToData(): void
+    {
+        $model = Ticket::fromArray(['priority' => 'urgent', 'labels' => []]);
+        $this->assertSame('urgent', $model['priority']);
+    }
+
+    #[Test]
+    public function testEnumWireFormatStableAcrossConstruction(): void
+    {
+        $fromScalar = Ticket::fromArray(['priority' => 'low', 'labels' => ['high']]);
+        $fromInstance = Ticket::fromArray(['priority' => TicketPriority::Low, 'labels' => [TicketPriority::High]]);
+        $this->assertSame(json_encode($fromScalar), json_encode($fromInstance));
+    }
 }