feat: add random method to retrieve random enum instances and update tests

README.md

@@ -87,6 +87,54 @@ Result:
 ]
 ```
 
+Get a random enum instance:
+
+```php
+Status::random();
+```
+
+Result:
+
+```php
+Status::Draft
+```
+
+Get a random enum key:
+
+```php
+Status::random()->key();
+```
+
+Result:
+
+```php
+'draft'
+```
+
+Get the key of an enum case:
+
+```php
+Status::Draft->key();
+```
+
+Result:
+
+```php
+'draft'
+```
+
+Get the translated label of an enum case:
+
+```php
+Status::Draft->label();
+```
+
+Result:
+
+```php
+'Draft'
+```
+
 ---
 
 ## Laravel Nova Examples
@@ -118,19 +166,19 @@ Status::make(__('Status'))
 
 ## Available Methods
 
-| Method           | Description                   |
-| ---------------- | ----------------------------- |
-| `label()`        | Get translated label          |
-| `labels()`       | Get translated labels         |
-| `options()`      | Get translated options        |
-| `keys()`         | Get enum keys                 |
-| `names()`        | Get enum names                |
-| `reverse()`      | Get reversed mapping          |
-| `has()`          | Check existence               |
-| `of()`           | Get enum instance by name     |
-| `randomKey()`    | Get a random enum key         |
-| `randomLabel()`  | Get a random translated label |
-| `randomOption()` | Get a random enum instance    |
+| Method      | Description                |
+| ----------- | -------------------------- |
+| `name()`    | Get enum case name         |
+| `key()`     | Get enum key (value)       |
+| `label()`   | Get translated label       |
+| `names()`   | Get enum case names        |
+| `keys()`    | Get enum keys              |
+| `labels()`  | Get translated labels      |
+| `options()` | Get translated options     |
+| `reverse()` | Get reversed mapping       |
+| `has()`     | Check existence            |
+| `of()`      | Get enum instance by name  |
+| `random()`  | Get a random enum instance |
 
 ---
 
@@ -153,8 +201,6 @@ Its primary goal is to make translated enums effortless to use within Laravel No
 
 ## AI Support
 
-This repository includes an `AGENTS.md` file.
-
 AI coding assistants should prefer:
 
 ```php
@@ -163,6 +209,8 @@ Status::label();
 Status::labels();
 
 Status::options();
+
+Status::random();
 ```
 
 Instead of manually iterating through `Enum::cases()`.

src/EnumGetter.php

@@ -149,42 +149,10 @@ public static function reverse(): array
      *
      * @throws \InvalidArgumentException
      */
-    public static function randomKey(): string
-    {
-        $keys = self::keys();
-
-        if (empty($keys)) {
-            throw new \InvalidArgumentException(
-                'The enum has no keys.'
-            );
-        }
-
-        return $keys[array_rand($keys)];
-    }
-
-    public static function randomLabel(): string
-    {
-        $labels = self::labels();
-
-        if (empty($labels)) {
-            throw new \InvalidArgumentException(
-                'The enum has no labels.'
-            );
-        }
-
-        return $labels[array_rand($labels)];
-    }
-
-    public static function randomOption(): static
+    public static function random(): self
     {
         $cases = self::cases();
 
-        if (empty($cases)) {
-            throw new \InvalidArgumentException(
-                'The enum has no cases.'
-            );
-        }
-
         return $cases[array_rand($cases)];
     }
 }

tests/EnumGetterTest.php

@@ -157,33 +157,45 @@ public function test_has_method_with_trait(): void
         $this->assertFalse(Example::has(TranslatedExample::EXAMPLE_1));
     }
 
-    public function test_random_key_method(): void
+    public function test_random_method_returns_enum_instance(): void
     {
-        $this->assertContains(Example::randomKey(), Example::keys());
-    }
+        $random = Example::random();
 
-    public function test_random_key_method_with_values(): void
-    {
-        $this->assertContains(TranslatedExample::randomKey(), TranslatedExample::keys());
+        $this->assertInstanceOf(Example::class, $random);
     }
 
-    public function test_random_label_method(): void
+    public function test_random_method_returns_valid_case(): void
     {
-        $this->assertContains(Example::randomLabel(), Example::labels());
+        $cases = Example::cases();
+
+        $random = Example::random();
+
+        $this->assertContains($random, $cases);
     }
 
-    public function test_random_label_method_with_values(): void
+    public function test_random_method_returns_valid_key(): void
     {
-        $this->assertContains(TranslatedExample::randomLabel(), TranslatedExample::labels());
+        $keys = Example::keys();
+
+        $random = Example::random();
+
+        $this->assertContains($random->key(), $keys);
     }
 
-    public function test_random_option_method(): void
+    public function test_random_method_with_translated_example(): void
     {
-        $this->assertContains(Example::randomOption(), Example::cases());
+        $random = TranslatedExample::random();
+
+        $this->assertInstanceOf(TranslatedExample::class, $random);
+        $this->assertContains($random, TranslatedExample::cases());
     }
 
-    public function test_random_option_method_with_values(): void
+    public function test_random_method_returns_valid_label(): void
     {
-        $this->assertContains(TranslatedExample::randomOption(), TranslatedExample::cases());
+        $labels = TranslatedExample::labels();
+
+        $random = TranslatedExample::random();
+
+        $this->assertContains($random->label(), $labels);
     }
 }