feat: #[EnumValue] attribute for per-case enum metadata

Closes the deeper portion of #740 that the original PR left as future work:
native PHP 8.1+ enum cases can now carry an explicit GraphQL description
and deprecation reason without relying on docblock parsing.

```php
#[Type]
enum Genre: string
{
    #[EnumValue(description: 'Fiction works including novels and short stories.')]
    case Fiction = 'fiction';

    #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')]
    case Poetry = 'poetry';
}
```

Naming: follows the GraphQL specification's term ("enum values", §3.5.2,
`__EnumValue`, `enumValues`) rather than the PHP language term "case".
This matches every other graphqlite attribute (`Type`, `Field`, `Query`,
`ExtendType`, …) which mirrors GraphQL spec names, and webonyx/graphql-php's
internal `EnumValueDefinition`. Targets `Attribute::TARGET_CLASS_CONSTANT`
so it applies to PHP enum cases.

Precedence: explicit `description` / `deprecationReason` on the attribute
win over docblock summary / `@deprecated` tag. Passing `''` deliberately
suppresses the fallback at that site, matching every other `description`
argument across the library. No-attribute cases continue to fall back to
docblock — BC preserved.

Adds `AnnotationReader::getEnumValueAnnotation(ReflectionEnumUnitCase)`
helper and threads it through `EnumTypeMapper::mapByClassName()` where
enum case metadata is aggregated.

Tests: 5 new unit tests (attribute defaults / description / deprecation
reason / both / empty string) plus 4 new integration tests over a new
fixture enum (attribute-supplied description, docblock fallback, explicit
deprecation, toggle-off suppresses docblock-only case). Full suite
537/537 green across cs-check, phpstan, and phpunit.

Author: oojacoboo

src/AnnotationReader.php

@@ -5,12 +5,14 @@
 namespace TheCodingMachine\GraphQLite;
 
 use ReflectionClass;
+use ReflectionEnumUnitCase;
 use ReflectionMethod;
 use ReflectionParameter;
 use ReflectionProperty;
 use TheCodingMachine\GraphQLite\Annotations\AbstractGraphQLElement;
 use TheCodingMachine\GraphQLite\Annotations\Decorate;
 use TheCodingMachine\GraphQLite\Annotations\EnumType;
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
 use TheCodingMachine\GraphQLite\Annotations\Exceptions\ClassNotFoundException;
 use TheCodingMachine\GraphQLite\Annotations\Exceptions\InvalidParameterException;
 use TheCodingMachine\GraphQLite\Annotations\ExtendType;
@@ -201,6 +203,24 @@ public function getEnumTypeAnnotation(ReflectionClass $refClass): EnumType|null
         return $this->getClassAnnotation($refClass, EnumType::class);
     }
 
+    /**
+     * Returns the {@see EnumValue} attribute declared on a PHP enum case, or null when no
+     * attribute is present. Callers use this to resolve the explicit description and deprecation
+     * reason before falling back to docblock parsing.
+     */
+    public function getEnumValueAnnotation(ReflectionEnumUnitCase $refCase): EnumValue|null
+    {
+        $attribute = $refCase->getAttributes(EnumValue::class)[0] ?? null;
+        if ($attribute === null) {
+            return null;
+        }
+
+        $instance = $attribute->newInstance();
+        assert($instance instanceof EnumValue);
+
+        return $instance;
+    }
+
     /** @param class-string<AbstractGraphQLElement> $annotationClass */
     public function getGraphQLElementAnnotation(ReflectionMethod $refMethod, string $annotationClass): AbstractGraphQLElement|null
     {

src/Annotations/EnumValue.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Annotations;
+
+use Attribute;
+
+/**
+ * Attaches GraphQL metadata to an individual enum case.
+ *
+ * Applied to cases of a PHP 8.1+ native enum exposed as a GraphQL enum type, this attribute
+ * provides the schema description and deprecation reason for that value without relying on
+ * docblock parsing — mirroring the explicit {@see Type::$description} and
+ * {@see Field::$description} pattern that the rest of the attribute system uses.
+ *
+ * The attribute is named after the GraphQL specification's term for an enum member ("enum
+ * value", see §3.5.2 of the spec and the `__EnumValue` introspection type), which matches the
+ * GraphQL-spec-mirroring naming convention of every other graphqlite attribute (`#[Type]`,
+ * `#[Field]`, `#[Query]`, etc.). The underlying PHP language construct is `case`; the GraphQL
+ * schema element it produces is an enum value.
+ *
+ * Example:
+ * ```php
+ * #[Type]
+ * enum Genre: string
+ * {
+ *     #[EnumValue(description: 'Fiction works including novels and short stories.')]
+ *     case Fiction = 'fiction';
+ *
+ *     #[EnumValue(deprecationReason: 'Use NonFiction::Essay instead.')]
+ *     case Essay = 'essay';
+ *
+ *     case Poetry = 'poetry'; // no explicit metadata — falls back to docblock
+ * }
+ * ```
+ *
+ * Precedence rules match the rest of the description system: an explicit `description` wins
+ * over any docblock summary on the case; an explicit `deprecationReason` wins over any
+ * `@deprecated` tag in the case docblock. Passing an empty-string description deliberately
+ * publishes an empty description and suppresses the docblock fallback at that site (see the
+ * {@see \TheCodingMachine\GraphQLite\Utils\DescriptionResolver} for details).
+ */
+#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
+final class EnumValue
+{
+    public function __construct(
+        public readonly string|null $description = null,
+        public readonly string|null $deprecationReason = null,
+    ) {
+    }
+}

src/Mappers/Root/EnumTypeMapper.php

@@ -139,17 +139,31 @@ private function mapByClassName(string $enumClass): EnumType|null
                 : null,
         );
 
-        /** @var array<string, string> $enumCaseDescriptions */
+        /** @var array<string, string|null> $enumCaseDescriptions */
         $enumCaseDescriptions = [];
         /** @var array<string, string> $enumCaseDeprecationReasons */
         $enumCaseDeprecationReasons = [];
 
         foreach ($reflectionEnum->getCases() as $reflectionEnumCase) {
             $docBlock = $this->docBlockFactory->create($reflectionEnumCase);
+            $enumValueAttribute = $this->annotationReader->getEnumValueAnnotation($reflectionEnumCase);
+
+            $enumCaseDescriptions[$reflectionEnumCase->getName()] = $this->descriptionResolver->resolve(
+                $enumValueAttribute?->description,
+                $docBlock->getSummary() ?: null,
+            );
+
+            $explicitDeprecation = $enumValueAttribute?->deprecationReason;
+            if ($explicitDeprecation !== null) {
+                // Explicit `deprecationReason` always wins; an empty string deliberately clears
+                // any @deprecated tag on the case docblock the same way an empty description
+                // blocks the docblock fallback.
+                if ($explicitDeprecation !== '') {
+                    $enumCaseDeprecationReasons[$reflectionEnumCase->getName()] = $explicitDeprecation;
+                }
+                continue;
+            }
 
-            $enumCaseDescriptions[$reflectionEnumCase->getName()] = $this->descriptionResolver->isDocblockFallbackEnabled()
-                ? ($docBlock->getSummary() ?: null)
-                : null;
             $deprecation = $docBlock->getTagsByName('deprecated')[0] ?? null;
 
             // phpcs:ignore

tests/Annotations/EnumValueTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Annotations;
+
+use PHPUnit\Framework\TestCase;
+
+class EnumValueTest extends TestCase
+{
+    public function testDefaults(): void
+    {
+        $enumValue = new EnumValue();
+
+        $this->assertNull($enumValue->description);
+        $this->assertNull($enumValue->deprecationReason);
+    }
+
+    public function testDescriptionOnly(): void
+    {
+        $enumValue = new EnumValue(description: 'Fiction genre.');
+
+        $this->assertSame('Fiction genre.', $enumValue->description);
+        $this->assertNull($enumValue->deprecationReason);
+    }
+
+    public function testDeprecationReasonOnly(): void
+    {
+        $enumValue = new EnumValue(deprecationReason: 'Use Essay instead.');
+
+        $this->assertNull($enumValue->description);
+        $this->assertSame('Use Essay instead.', $enumValue->deprecationReason);
+    }
+
+    public function testBothValues(): void
+    {
+        $enumValue = new EnumValue(
+            description: 'Fiction works.',
+            deprecationReason: 'Use a subgenre.',
+        );
+
+        $this->assertSame('Fiction works.', $enumValue->description);
+        $this->assertSame('Use a subgenre.', $enumValue->deprecationReason);
+    }
+
+    public function testDescriptionPreservesEmptyString(): void
+    {
+        // '' is the deliberate "explicit empty" signal that blocks docblock fallback downstream.
+        $enumValue = new EnumValue(description: '');
+
+        $this->assertSame('', $enumValue->description);
+    }
+}

tests/Fixtures/Description/Genre.php

@@ -4,6 +4,7 @@
 
 namespace TheCodingMachine\GraphQLite\Fixtures\Description;
 
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
 use TheCodingMachine\GraphQLite\Annotations\Type;
 
 /**
@@ -12,7 +13,15 @@
 #[Type(description: 'Editorial classification of a book.')]
 enum Genre: string
 {
+    #[EnumValue(description: 'Fiction works including novels and short stories.')]
     case Fiction = 'fiction';
+
+    /**
+     * This docblock description should appear on the NonFiction enum value because no
+     * #[EnumValue] attribute is declared — it exercises the docblock fallback.
+     */
     case NonFiction = 'non-fiction';
+
+    #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')]
     case Poetry = 'poetry';
 }

tests/Integration/DescriptionTest.php

@@ -96,6 +96,54 @@ public function testExplicitDescriptionOnNativeEnumViaType(): void
         $this->assertSame('Editorial classification of a book.', $genreType->description);
     }
 
+    public function testEnumValueAttributeProvidesCaseDescription(): void
+    {
+        $schema = $this->buildSchema(Book::class);
+
+        $genreType = $schema->getType('Genre');
+        $fictionValue = $genreType->getValue('Fiction');
+        $this->assertSame('Fiction works including novels and short stories.', $fictionValue->description);
+    }
+
+    public function testEnumCaseWithoutAttributeFallsBackToDocblock(): void
+    {
+        $schema = $this->buildSchema(Book::class);
+
+        $genreType = $schema->getType('Genre');
+        $nonFictionValue = $genreType->getValue('NonFiction');
+        // The NonFiction case has no #[EnumValue] attribute, so its description comes from the docblock.
+        $this->assertNotNull($nonFictionValue->description);
+        $this->assertStringContainsString(
+            'This docblock description should appear on the NonFiction enum value',
+            $nonFictionValue->description,
+        );
+    }
+
+    public function testEnumValueAttributeProvidesDeprecationReason(): void
+    {
+        $schema = $this->buildSchema(Book::class);
+
+        $genreType = $schema->getType('Genre');
+        $poetryValue = $genreType->getValue('Poetry');
+        $this->assertSame('Use Fiction::Verse instead.', $poetryValue->deprecationReason);
+    }
+
+    public function testDisablingDocblockFallbackSuppressesEnumCaseDescription(): void
+    {
+        $schema = $this->buildSchema(Book::class, docblockDescriptions: false);
+
+        $genreType = $schema->getType('Genre');
+
+        // Fiction has an explicit #[EnumValue] description — still present.
+        $this->assertSame(
+            'Fiction works including novels and short stories.',
+            $genreType->getValue('Fiction')->description,
+        );
+
+        // NonFiction relied on its docblock summary — with the toggle off, it must disappear.
+        $this->assertNull($genreType->getValue('NonFiction')->description);
+    }
+
     public function testExtendTypeSuppliesDescriptionWhenBaseTypeHasNone(): void
     {
         $schema = $this->buildSchema(Book::class);

website/docs/annotations-reference.md

@@ -311,6 +311,30 @@ Attribute      | Compulsory | Type | Definition
 *for*          | *yes*      | string | The name of the PHP parameter
 *constraint*   | *yes       | annotation | One (or many) Symfony validation attributes.
 
+## #[EnumValue]
+
+The `#[EnumValue]` attribute attaches GraphQL schema metadata (description, deprecation reason)
+to an individual case of a PHP 8.1+ native enum that is exposed as a GraphQL enum type.
+
+**Applies on**: cases of an enum annotated (directly or indirectly) with `#[Type]`.
+
+Attribute         | Compulsory | Type   | Definition
+------------------|------------|--------|-----------
+description       | *no*       | string | Description of the enum value. When omitted, the case's PHP docblock summary is used (see [schema descriptions](descriptions.md#enum-value-descriptions)). An explicit empty string `''` deliberately suppresses the docblock fallback.
+deprecationReason | *no*       | string | Deprecation reason published to the schema. When omitted, the `@deprecated` tag on the case docblock is used. An explicit empty string `''` deliberately clears any inherited `@deprecated` tag.
+
+```php
+#[Type]
+enum Genre: string
+{
+    #[EnumValue(description: 'Fiction works including novels and short stories.')]
+    case Fiction = 'fiction';
+
+    #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')]
+    case Poetry = 'poetry';
+}
+```
+
 ## ~~@EnumType~~
 
 *Deprecated: Use [PHP 8.1's native Enums](https://www.php.net/manual/en/language.types.enumerations.php) instead with a [#[Type]](#type-annotation).*

website/docs/descriptions.md

@@ -37,6 +37,7 @@ The attributes that accept `description`:
 - `#[Type]`, `#[ExtendType]` — object and enum types
 - `#[Factory]` — input types produced by factories
 - `#[Field]`, `#[Input]`, `#[SourceField]`, `#[MagicField]` — fields on output and input types
+- `#[EnumValue]` — individual cases of an enum type (see [Enum value descriptions](#enum-value-descriptions))
 
 ## Docblock fallback
 
@@ -88,6 +89,46 @@ disabling the whole fallback, pass an empty string:
 public function internalOnly(): Foo { /* ... */ }
 ```
 
+## Enum value descriptions
+
+Native PHP 8.1 enums mapped to GraphQL enum types get per-case metadata via the `#[EnumValue]`
+attribute applied to individual cases:
+
+```php
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
+use TheCodingMachine\GraphQLite\Annotations\Type;
+
+#[Type]
+enum Genre: string
+{
+    #[EnumValue(description: 'Fiction works including novels and short stories.')]
+    case Fiction = 'fiction';
+
+    #[EnumValue(deprecationReason: 'Use Fiction::Verse instead.')]
+    case Poetry = 'poetry';
+
+    /**
+     * Works grounded in verifiable facts.
+     */
+    case NonFiction = 'non-fiction'; // no attribute — description comes from the docblock
+}
+```
+
+The attribute name mirrors the GraphQL specification's term ("enum values", see
+[spec §3.5.2](https://spec.graphql.org/October2021/#sec-Enum-Values)) and matches webonyx/graphql-php's
+`EnumValueDefinition`. The underlying PHP construct is a `case`; the GraphQL element it produces
+is an enum value.
+
+`#[EnumValue]` accepts:
+
+- `description` — schema description for this enum value. Omitting it falls back to the case
+  docblock summary, subject to the same precedence rules as every other attribute's
+  `description` argument. An explicit empty string `''` deliberately suppresses the docblock
+  fallback.
+- `deprecationReason` — published as the enum value's `deprecationReason` in the schema.
+  Omitting it falls back to the `@deprecated` tag on the case docblock. An explicit empty string
+  `''` deliberately clears any inherited `@deprecated` tag.
+
 ## Description uniqueness on `#[ExtendType]`
 
 A GraphQL type has exactly one description, so GraphQLite enforces that the description for a