feat: deprecation notice for enum cases missing #[EnumValue]

Announces the upcoming opt-in migration for PHP enums mapped to GraphQL
enum types. Today every case is automatically exposed; a future major
release will require #[EnumValue] on each case that should participate
in the schema, matching the opt-in model #[Field] already uses for
methods and properties on object types.

The practical win is selective exposure: an internal enum case can opt
out of the public schema simply by omitting #[EnumValue], instead of
forcing schema authors to split an enum or rename cases.

Runtime behaviour is unchanged. When an enum annotated with #[Type]
exposes any case without an #[EnumValue] attribute, EnumTypeMapper
emits an E_USER_DEPRECATED notice that names the specific cases so the
migration path is mechanical — matching graphqlite's existing
deprecation pattern (e.g. addControllerNamespace, setGlobTTL).

Tests: +1 explicit deprecation assertion (using PHPUnit 11's
expectUserDeprecationMessageMatches). Existing integration tests that
exercise the Genre fixture surface the notice via PHPUnit's deprecation
reporting, confirming the warning fires in realistic scenarios. Full
suite 538/538 green across cs-check, phpstan, and phpunit; 4 intentional
deprecation events reported.

Docs: descriptions.md gains a "Future migration" subsection describing
the planned opt-in model and the current advisory notice.

Author: oojacoboo

src/Mappers/Root/EnumTypeMapper.php

@@ -30,7 +30,12 @@
 use function array_values;
 use function assert;
 use function enum_exists;
+use function implode;
 use function ltrim;
+use function sprintf;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
 
 /**
  * Maps an enum class to a GraphQL type (only available in PHP>=8.1)
@@ -143,11 +148,17 @@ private function mapByClassName(string $enumClass): EnumType|null
         $enumCaseDescriptions = [];
         /** @var array<string, string> $enumCaseDeprecationReasons */
         $enumCaseDeprecationReasons = [];
+        /** @var list<string> $casesMissingEnumValueAttribute */
+        $casesMissingEnumValueAttribute = [];
 
         foreach ($reflectionEnum->getCases() as $reflectionEnumCase) {
             $docBlock = $this->docBlockFactory->create($reflectionEnumCase);
             $enumValueAttribute = $this->annotationReader->getEnumValueAnnotation($reflectionEnumCase);
 
+            if ($enumValueAttribute === null) {
+                $casesMissingEnumValueAttribute[] = $reflectionEnumCase->getName();
+            }
+
             $enumCaseDescriptions[$reflectionEnumCase->getName()] = $this->descriptionResolver->resolve(
                 $enumValueAttribute?->description,
                 $docBlock->getSummary() ?: null,
@@ -172,11 +183,45 @@ private function mapByClassName(string $enumClass): EnumType|null
             }
         }
 
+        $this->warnAboutCasesMissingEnumValueAttribute($enumClass, $casesMissingEnumValueAttribute);
+
         $type = new EnumType($enumClass, $typeName, $enumDescription, $enumCaseDescriptions, $enumCaseDeprecationReasons, $useValues);
 
         return $this->cacheByName[$type->name] = $this->cacheByClass[$enumClass] = $type;
     }
 
+    /**
+     * Emits a deprecation notice when a GraphQL-mapped enum exposes one or more cases without a
+     * matching {@see EnumValue} attribute.
+     *
+     * Today every case is automatically exposed in the schema — this call site keeps that
+     * behaviour intact. The notice announces the planned migration: a future major release will
+     * require `#[EnumValue]` on each case that should participate in the schema, mirroring
+     * `#[Field]`'s opt-in model on classes. Until then, adopters can start annotating cases
+     * incrementally; the warning lists the specific cases that would be dropped after the
+     * future default flip so the migration path is mechanical.
+     *
+     * @param class-string<UnitEnum>  $enumClass
+     * @param list<string>            $casesMissingAttribute
+     */
+    private function warnAboutCasesMissingEnumValueAttribute(string $enumClass, array $casesMissingAttribute): void
+    {
+        if ($casesMissingAttribute === []) {
+            return;
+        }
+
+        trigger_error(
+            sprintf(
+                'Enum "%s" is mapped to a GraphQL enum type but exposes one or more cases without a #[EnumValue] attribute. '
+                . 'Today every case is automatically exposed; a future major release will require #[EnumValue] on each case that should participate in the schema, mirroring #[Field]\'s opt-in model. '
+                . 'Add #[EnumValue] to each case you want to keep exposed. Cases currently exposed without an attribute: %s.',
+                $enumClass,
+                implode(', ', $casesMissingAttribute),
+            ),
+            E_USER_DEPRECATED,
+        );
+    }
+
     private function getTypeName(ReflectionClass $reflectionClass): string
     {
         $typeAnnotation = $this->annotationReader->getTypeAnnotation($reflectionClass);

tests/Integration/DescriptionTest.php

@@ -105,6 +105,20 @@ public function testEnumValueAttributeProvidesCaseDescription(): void
         $this->assertSame('Fiction works including novels and short stories.', $fictionValue->description);
     }
 
+    public function testEnumWithCasesMissingEnumValueAttributeTriggersDeprecation(): void
+    {
+        // The Genre fixture deliberately leaves NonFiction without #[EnumValue] to exercise the
+        // docblock-fallback path and to surface the deprecation announcing the future opt-in
+        // migration. PHPUnit 11's expectUserDeprecationMessageMatches hooks into the library's
+        // own error handler so the assertion works consistently with how deprecations surface
+        // in CI output.
+        $this->expectUserDeprecationMessageMatches('/#\[EnumValue\].*future major.*NonFiction/s');
+
+        $schema = $this->buildSchema(Book::class);
+        // Force enum resolution — types are lazy-mapped until referenced.
+        $schema->getType('Genre');
+    }
+
     public function testEnumCaseWithoutAttributeFallsBackToDocblock(): void
     {
         $schema = $this->buildSchema(Book::class);

website/docs/descriptions.md

@@ -129,6 +129,25 @@ is an enum value.
   Omitting it falls back to the `@deprecated` tag on the case docblock. An explicit empty string
   `''` deliberately clears any inherited `@deprecated` tag.
 
+### Future migration: `#[EnumValue]` will become required per case
+
+Today every case of a `#[Type]`-mapped enum is automatically exposed in the GraphQL schema. A
+future major release will flip this to an opt-in model: **only cases carrying an explicit
+`#[EnumValue]` attribute will be exposed**, mirroring the way `#[Field]` opts individual
+methods and properties into an object type.
+
+The benefit is selective exposure — today there is no way to map a subset of a PHP enum into
+GraphQL, which forces schema authors to split an enum into two or rename cases. Under the
+opt-in model, an internal enum case can simply omit `#[EnumValue]` to stay out of the public
+schema.
+
+To surface the upcoming change, GraphQLite already emits a PHP `E_USER_DEPRECATED` notice at
+schema build time when an enum annotated with `#[Type]` exposes any case without an
+`#[EnumValue]` attribute. The notice names the specific cases that would be dropped after the
+flip so the migration path is mechanical: add `#[EnumValue]` to every case you want to keep.
+No runtime behaviour changes today — the notice only signals what the future default will
+require.
+
 ## Description uniqueness on `#[ExtendType]`
 
 A GraphQL type has exactly one description, so GraphQLite enforces that the description for a