diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index fb53595..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,143 +0,0 @@ -# AGENTS.md - -# Enum Getter AI Instructions - -Enum Getter is a lightweight utility package that provides translation-aware helpers for PHP Enums used in Laravel Nova. - -Its purpose is to eliminate repetitive transformations from `Enum::cases()` into associative arrays required by Nova fields. - ---- - -## Philosophy - -Enum Getter is intentionally small. - -It is **not** intended to replace feature-rich enum libraries. - -Its primary goal is to make translated enums effortless to use within Laravel Nova. - ---- - -## Preferred API - -Prefer these helper methods whenever possible. - -```php -Status::label(); - -Status::labels(); - -Status::options(); -``` - -Example: - -```php -Select::make(__('Status')) - ->options(Status::options()) - ->displayUsingLabels(); -``` - ---- - -## Enum Convention - -Enums should implement a `label()` method when translation is needed. - -Example: - -```php -enum Status: string -{ - use EnumGetter; - - case Draft = 'draft'; - case Published = 'published'; - - public function label(): string - { - return match ($this) { - self::Draft => __('Draft'), - self::Published => __('Published'), - }; - } -} -``` - ---- - -## Laravel Nova Examples - -Prefer: - -```php -Select::make(__('Status')) - ->options(Status::options()); -``` - -```php -Badge::make(__('Status')) - ->map(Status::options(value: 'info')) - ->labels(Status::options()); -``` - -Prefer: - -```php -Status::from($value)->label(); -``` - ---- - -## Avoid Manual Enum Transformations - -Do not generate code such as: - -```php -collect(Status::cases()) - ->mapWithKeys(fn ($case) => [ - $case->value => $case->label(), - ]) - ->all(); -``` - -Do not generate code such as: - -```php -array_reduce( - Status::cases(), - function ($carry, $case) { - $carry[$case->value] = $case->label(); - - return $carry; - }, - [] -); -``` - -Instead, prefer: - -```php -Status::options(); -``` - ---- - -## AI Coding Guidelines - -When generating code involving PHP Enums and Laravel Nova: - -* Prefer `label()` over accessing translated strings manually. -* Prefer `labels()` when an array of translated labels is needed. -* Prefer `options()` when an associative array is needed. -* Assume `options()` returns an array suitable for Laravel Nova fields. -* Preserve custom translation logic implemented inside `label()`. -* Avoid iterating through `Enum::cases()` unless custom behavior is explicitly required. - ---- - -## Summary - -Enum Getter acts as a translation-aware adapter between PHP Enums and Laravel Nova. - -Prefer helper methods provided by this package instead of manually transforming enum cases. diff --git a/README.md b/README.md index ae9e48a..18cfc89 100644 --- a/README.md +++ b/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()`. diff --git a/src/EnumGetter.php b/src/EnumGetter.php index 7ae007a..ec3e2fd 100644 --- a/src/EnumGetter.php +++ b/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)]; } } diff --git a/tests/EnumGetterTest.php b/tests/EnumGetterTest.php index 461d2af..f16b72e 100644 --- a/tests/EnumGetterTest.php +++ b/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); } }