Make deprecated introspection optional for legacy servers

Author: johnxy84

CHANGELOG.md

@@ -9,6 +9,10 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+### Changed
+
+- Allow omitting deprecated introspection arguments/fields for legacy servers
+
 ## v15.30.2
 
 ### Fixed

src/Type/Introspection.php

@@ -30,6 +30,7 @@
  * @phpstan-type IntrospectionOptions array{
  *     descriptions?: bool,
  *     directiveIsRepeatable?: bool,
+ *     includeDeprecated?: bool,
  *     schemaDescription?: bool,
  *     typeIsOneOf?: bool,
  * }
@@ -41,10 +42,15 @@
  * - directiveIsRepeatable
  *   Include field `isRepeatable` for directives?
  *   Default: false
+ * - includeDeprecated
+ *   Include deprecated fields/args/enum values/input fields and related indicators
+ *   (isDeprecated/deprecationReason) in the introspection query
+ *   Default: true
+ *
+ *   @see https://graphql-ruby.org/api-doc/1.12.1/GraphQL/Introspection.html
  * - typeIsOneOf
  *   Include field `isOneOf` for types?
  *   Default: false
- *
  * @see \GraphQL\Tests\Type\IntrospectionTest
  */
 class Introspection
@@ -86,6 +92,7 @@ public static function getIntrospectionQuery(array $options = []): string
         $optionsWithDefaults = array_merge([
             'descriptions' => true,
             'directiveIsRepeatable' => false,
+            'includeDeprecated' => true,
             'schemaDescription' => false,
             'typeIsOneOf' => false,
         ], $options);
@@ -102,6 +109,13 @@ public static function getIntrospectionQuery(array $options = []): string
         $typeIsOneOf = $optionsWithDefaults['typeIsOneOf']
             ? 'isOneOf'
             : '';
+        $includeDeprecated = $optionsWithDefaults['includeDeprecated'];
+        $includeDeprecatedArg = $includeDeprecated
+            ? '(includeDeprecated: true)'
+            : '';
+        $deprecationIndicators = $includeDeprecated
+            ? "      isDeprecated\n      deprecationReason"
+            : '';
 
         return <<<GRAPHQL
   query IntrospectionQuery {
@@ -116,7 +130,7 @@ public static function getIntrospectionQuery(array $options = []): string
       directives {
         name
         {$descriptions}
-        args(includeDeprecated: true) {
+        args{$includeDeprecatedArg} {
           ...InputValue
         }
         {$directiveIsRepeatable}
@@ -130,29 +144,27 @@ public static function getIntrospectionQuery(array $options = []): string
     name
     {$descriptions}
     {$typeIsOneOf}
-    fields(includeDeprecated: true) {
+    fields{$includeDeprecatedArg} {
       name
       {$descriptions}
-      args(includeDeprecated: true) {
+      args{$includeDeprecatedArg} {
         ...InputValue
       }
       type {
         ...TypeRef
       }
-      isDeprecated
-      deprecationReason
+      {$deprecationIndicators}
     }
-    inputFields(includeDeprecated: true) {
+    inputFields{$includeDeprecatedArg} {
       ...InputValue
     }
     interfaces {
       ...TypeRef
     }
-    enumValues(includeDeprecated: true) {
+    enumValues{$includeDeprecatedArg} {
       name
       {$descriptions}
-      isDeprecated
-      deprecationReason
+      {$deprecationIndicators}
     }
     possibleTypes {
       ...TypeRef
@@ -164,8 +176,7 @@ enumValues(includeDeprecated: true) {
     {$descriptions}
     type { ...TypeRef }
     defaultValue
-    isDeprecated
-    deprecationReason
+    {$deprecationIndicators}
   }
 
   fragment TypeRef on __Type {

src/Utils/BuildClientSchema.php

@@ -424,7 +424,7 @@ private function buildEnumDef(array $enum): EnumType
         foreach ($enum['enumValues'] as $value) {
             $values[$value['name']] = [
                 'description' => $value['description'],
-                'deprecationReason' => $value['deprecationReason'],
+                'deprecationReason' => $value['deprecationReason'] ?? null,
             ];
         }
 
@@ -479,7 +479,7 @@ private function buildFieldDefMap(array $typeIntrospection): array
 
             $map[$field['name']] = [
                 'description' => $field['description'],
-                'deprecationReason' => $field['deprecationReason'],
+                'deprecationReason' => $field['deprecationReason'] ?? null,
                 'type' => $this->getOutputType($field['type']),
                 'args' => $this->buildInputValueDefMap($field['args']),
             ];

tests/Type/IntrospectionTest.php

@@ -2020,4 +2020,27 @@ public function testIncludeDescriptionFieldOnSchema(): void
         preg_match_all('/\bdescription\b/', Introspection::getIntrospectionQuery(['descriptions' => false, 'schemaDescription' => true]), $matches);
         self::assertCount(0, $matches[0]);
     }
+
+    /** @see it('excludes deprecated fields and indicators when disabled') */
+    public function testExcludeDeprecatedFieldsAndIndicatorsWhenDisabled(): void
+    {
+        $source = Introspection::getIntrospectionQuery(['includeDeprecated' => false]);
+
+        self::assertStringNotContainsString('includeDeprecated: true', $source);
+        self::assertStringNotContainsString('includeDeprecated: false', $source);
+        self::assertStringContainsString('args {', $source);
+        self::assertStringContainsString('fields {', $source);
+        self::assertStringContainsString('inputFields {', $source);
+        self::assertStringContainsString('enumValues {', $source);
+        self::assertStringNotContainsString('isDeprecated', $source);
+        self::assertStringNotContainsString('deprecationReason', $source);
+    }
+
+    /** @see it('keeps deprecated args enabled by default') */
+    public function testIncludeDeprecatedArgumentsByDefault(): void
+    {
+        $source = Introspection::getIntrospectionQuery();
+
+        self::assertStringContainsString('(includeDeprecated: true)', $source);
+    }
 }

tests/Utils/BuildClientSchemaTest.php

@@ -166,6 +166,39 @@ public function testUsesBuiltInScalarsWhenPossible(): void
         );
     }
 
+    /** @see it('builds a schema from introspection without deprecated fields') */
+    public function testBuildsSchemaFromIntrospectionWithoutDeprecatedFields(): void
+    {
+        $sdl = '
+          type Query {
+            active: String
+            legacy: String @deprecated(reason: "Use active")
+          }
+
+          enum Status {
+            OK
+            OLD @deprecated(reason: "Use OK")
+          }
+        ';
+
+        $schema = BuildSchema::build($sdl);
+        $introspection = Introspection::fromSchema($schema, [
+            'includeDeprecated' => false,
+        ]);
+
+        $clientSchema = BuildClientSchema::build($introspection);
+
+        $queryType = $clientSchema->getQueryType();
+        self::assertNotNull($queryType);
+        self::assertArrayHasKey('active', $queryType->getFields());
+        self::assertArrayNotHasKey('legacy', $queryType->getFields());
+
+        $statusEnum = $clientSchema->getType('Status');
+        self::assertInstanceOf(EnumType::class, $statusEnum);
+        self::assertNotNull($statusEnum->getValue('OK'));
+        self::assertNull($statusEnum->getValue('OLD'));
+    }
+
     /** it('includes standard types only if they are used', () => {. */
     public function testIncludesStandardTypesOnlyIfTheyAreUsed(): void
     {