Introduce deprecationReason

jerowork · jerowork · commit 62e478c5243b · 2025-01-07T12:43:35.000+01:00
diff --git a/docs/todo.md b/docs/todo.md
@@ -1,7 +1,7 @@
 # Todo
 This library is still work in progress, and misses some valuable features:
 
-- Introduction of `#[Deprecated]` attribute
+- ~~Introduction of `#[Deprecated]` attribute~~
 - ~~Overwrite type via attributes~~
 - ~~Allow simple lists (array type)~~
 - Connection, edge, nodes (see https://relay.dev/graphql/connections.htm)
diff --git a/docs/usage.md b/docs/usage.md
@@ -1,15 +1,17 @@
 # Usage
+
 At minimum, a query and mutation needs to be defined to build a valid schema.
 
 ## Attributes
+
 The following attributes can be used:
 
 - `#[Mutation]`
 - `#[Query]`
 - `#[InputType]`
 - `#[Type]`
 - `#[Enum]`
-  - `#[EnumValue]`
+    - `#[EnumValue]`
 - `#[Field]`
 - `#[Arg]`
 
@@ -63,11 +65,12 @@ Mutations and queries:
 
 Both `#[Mutation]` and `#[Query]` attribute can be configured:
 
-| Option        | Description                                                                                                                                                                                                                                                                                                                                                                            |
-|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `name`        | Set custom name of mutation or query (instead of based on class)                                                                                                                                                                                                                                                                                                                       |
-| `description` | Set description of the mutation or query, readable in the GraphQL schema                                                                                                                                                                                                                                                                                                               |
-| `type`        | Set custom return type; it can be:<br/>- A Type (FQCN)<br/>- A `ScalarType` (e.g. `ScalarType::Int`)<br/>- A `ListType` (e.g. `new ListType(ScalarType::Int)`)<br/>- A `NullableType` (e.g. `new NullableType(SomeType::class)`)<br/>- A combination of `ListType` and `NullableType` and a Type FQCN or `ScalarType` <br/>(e.g. `new NullableType(new ListType(ScalarType::String))`) |
+| Option              | Description                                                                                                                                                                                                                                                                                                                                                                            |
+|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`              | Set custom name of mutation or query (instead of based on class)                                                                                                                                                                                                                                                                                                                       |
+| `description`       | Set description of the mutation or query, readable in the GraphQL schema                                                                                                                                                                                                                                                                                                               |
+| `type`              | Set custom return type; it can be:<br/>- A Type (FQCN)<br/>- A `ScalarType` (e.g. `ScalarType::Int`)<br/>- A `ListType` (e.g. `new ListType(ScalarType::Int)`)<br/>- A `NullableType` (e.g. `new NullableType(SomeType::class)`)<br/>- A combination of `ListType` and `NullableType` and a Type FQCN or `ScalarType` <br/>(e.g. `new NullableType(new ListType(ScalarType::String))`) |
+| `deprecationReason` | If set, deprecates the mutation or query                                                                                                                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                          |
 
 ### InputType
 
@@ -220,9 +223,10 @@ Each case in the `enum` type can be configured as well, with the `#[EnumValue]`
 
 `#[EnumValue]` attribute can be configured:
 
-| Option        | Description                                                      |
-|---------------|------------------------------------------------------------------|
-| `description` | Set description of the enum case, readable in the GraphQL schema |
+| Option              | Description                                                      |
+|---------------------|------------------------------------------------------------------|
+| `description`       | Set description of the enum case, readable in the GraphQL schema |
+| `deprecationReason` | If set, deprecates the case                                      |                                                                                                                                                                                                                                                                                                                                                          |
 
 ### Field
 
@@ -273,11 +277,12 @@ final readonly class YourInputType
 
 `#[Field]` attribute can be configured:
 
-| Option        | Description                                                                                                                                                                                                                                                                                                                                                                            |
-|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `name`        | Set custom name of field (instead of based on class)                                                                                                                                                                                                                                                                                                                                   |
-| `description` | Set description of the field, readable in the GraphQL schema                                                                                                                                                                                                                                                                                                                           |
-| `type`        | Set custom return type; it can be:<br/>- A Type (FQCN)<br/>- A `ScalarType` (e.g. `ScalarType::Int`)<br/>- A `ListType` (e.g. `new ListType(ScalarType::Int)`)<br/>- A `NullableType` (e.g. `new NullableType(SomeType::class)`)<br/>- A combination of `ListType` and `NullableType` and a Type FQCN or `ScalarType` <br/>(e.g. `new NullableType(new ListType(ScalarType::String))`) |
+| Option              | Description                                                                                                                                                                                                                                                                                                                                                                            |
+|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`              | Set custom name of field (instead of based on class)                                                                                                                                                                                                                                                                                                                                   |
+| `description`       | Set description of the field, readable in the GraphQL schema                                                                                                                                                                                                                                                                                                                           |
+| `type`              | Set custom return type; it can be:<br/>- A Type (FQCN)<br/>- A `ScalarType` (e.g. `ScalarType::Int`)<br/>- A `ListType` (e.g. `new ListType(ScalarType::Int)`)<br/>- A `NullableType` (e.g. `new NullableType(SomeType::class)`)<br/>- A combination of `ListType` and `NullableType` and a Type FQCN or `ScalarType` <br/>(e.g. `new NullableType(new ListType(ScalarType::String))`) |
+| `deprecationReason` | If set, deprecates the field (`#[Type]` only)                                                                                                                                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                          |
 
 ### Arg
 
diff --git a/src/Attribute/EnumValue.php b/src/Attribute/EnumValue.php
@@ -11,5 +11,6 @@
 {
     public function __construct(
         public ?string $description = null,
+        public ?string $deprecationReason = null,
     ) {}
 }
diff --git a/src/Attribute/Field.php b/src/Attribute/Field.php
@@ -18,6 +18,7 @@ public function __construct(
         public ?string $name = null,
         public ?string $description = null,
         public string|Type|ScalarType|null $type = null,
+        public ?string $deprecationReason = null,
     ) {}
 
     public function getName(): ?string
diff --git a/src/Attribute/Mutation.php b/src/Attribute/Mutation.php
@@ -18,6 +18,7 @@ public function __construct(
         public ?string $name = null,
         public ?string $description = null,
         public string|Type|ScalarType|null $type = null,
+        public ?string $deprecationReason = null,
     ) {}
 
     public function getName(): ?string
diff --git a/src/Attribute/Query.php b/src/Attribute/Query.php
@@ -18,6 +18,7 @@ public function __construct(
         public ?string $name = null,
         public ?string $description = null,
         public string|Type|ScalarType|null $type = null,
+        public ?string $deprecationReason = null,
     ) {}
 
     public function getName(): ?string
diff --git a/src/Parser/Node/Child/FieldNode.php b/src/Parser/Node/Child/FieldNode.php
@@ -19,5 +19,6 @@ public function __construct(
         public FieldNodeType $fieldType,
         public ?string $methodName,
         public ?string $propertyName,
+        public ?string $deprecationReason,
     ) {}
 }
diff --git a/src/Parser/Node/EnumValueNode.php b/src/Parser/Node/EnumValueNode.php
@@ -9,5 +9,6 @@
     public function __construct(
         public string $value,
         public ?string $description,
+        public ?string $deprecationReason,
     ) {}
 }
diff --git a/src/Parser/Node/MutationNode.php b/src/Parser/Node/MutationNode.php
@@ -19,6 +19,7 @@ public function __construct(
         public array $argNodes,
         public Type $outputType,
         public string $methodName,
+        public ?string $deprecationReason,
     ) {}
 
     public function getClassName(): string
diff --git a/src/Parser/Node/QueryNode.php b/src/Parser/Node/QueryNode.php
@@ -19,6 +19,7 @@ public function __construct(
         public array $argNodes,
         public Type $outputType,
         public string $methodName,
+        public ?string $deprecationReason,
     ) {}
 
     public function getClassName(): string
diff --git a/src/Parser/NodeParser/Child/ClassFieldNodesParser.php b/src/Parser/NodeParser/Child/ClassFieldNodesParser.php
@@ -55,6 +55,7 @@ public function parse(ReflectionClass $class): array
                 FieldNodeType::Property,
                 null,
                 $property->getName(),
+                $fieldAttribute->deprecationReason,
             );
         }
 
@@ -79,6 +80,7 @@ public function parse(ReflectionClass $class): array
                 FieldNodeType::Method,
                 $method->getName(),
                 null,
+                $fieldAttribute->deprecationReason,
             );
         }
 
diff --git a/src/Parser/NodeParser/EnumNodeParser.php b/src/Parser/NodeParser/EnumNodeParser.php
@@ -76,6 +76,7 @@ private function getValues(ReflectionClass $class): array
             $cases[] = new EnumValueNode(
                 (string) $value->value,
                 $enumAttribute?->description,
+                $enumAttribute?->deprecationReason,
             );
         }
 
diff --git a/src/Parser/NodeParser/MutationNodeParser.php b/src/Parser/NodeParser/MutationNodeParser.php
@@ -49,6 +49,7 @@ public function parse(ReflectionClass $class): Node
             $this->methodArgNodesParser->parse($method),
             $type,
             $method->getName(),
+            $attribute->deprecationReason,
         );
     }
 }
diff --git a/src/Parser/NodeParser/QueryNodeParser.php b/src/Parser/NodeParser/QueryNodeParser.php
@@ -49,6 +49,7 @@ public function parse(ReflectionClass $class): Node
             $this->methodArgNodesParser->parse($method),
             $type,
             $method->getName(),
+            $attribute->deprecationReason,
         );
     }
 }
diff --git a/src/TypeBuilder/Object/EnumObjectTypeBuilder.php b/src/TypeBuilder/Object/EnumObjectTypeBuilder.php
@@ -28,10 +28,16 @@ public function build(Node $node, TypeBuilder $typeBuilder, Ast $ast): Type
     {
         $values = [];
         foreach ($node->cases as $case) {
-            $values[$case->value] = [
+            $value = [
                 'value' => $case->value,
                 'description' => $case->description,
             ];
+
+            if ($case->deprecationReason !== null) {
+                $value['deprecationReason'] = $case->deprecationReason;
+            }
+
+            $values[$case->value] = $value;
         }
 
         return new EnumType([
diff --git a/src/TypeBuilder/Object/TypeObjectTypeBuilder.php b/src/TypeBuilder/Object/TypeObjectTypeBuilder.php
@@ -57,13 +57,19 @@ private function buildFields(TypeNode $node, TypeBuilder $typeBuilder, Ast $ast)
         $fields = [];
 
         foreach ($node->fieldNodes as $fieldNode) {
-            $fields[] = [
+            $field = [
                 'name' => $fieldNode->name,
                 'type' => $typeBuilder->build($fieldNode->type, $ast),
                 'description' => $fieldNode->description,
                 'args' => $this->buildArgs($fieldNode, $typeBuilder, $ast),
                 'resolve' => $this->typeResolver->resolve($fieldNode, $ast),
             ];
+
+            if ($fieldNode->deprecationReason !== null) {
+                $field['deprecationReason'] = $fieldNode->deprecationReason;
+            }
+
+            $fields[] = $field;
         }
 
         return $fields;
diff --git a/src/TypeBuilder/RootTypeBuilder.php b/src/TypeBuilder/RootTypeBuilder.php
@@ -40,12 +40,18 @@ public function build(QueryNode|MutationNode $node, Ast $ast): array
             ];
         }
 
-        return [
+        $root = [
             'name' => $node->name,
             'type' => $this->typeBuilder->build($node->outputType, $ast),
             'description' => $node->description,
             'args' => $args,
             'resolve' => $this->rootTypeResolver->resolve($node, $ast),
         ];
+
+        if ($node->deprecationReason !== null) {
+            $root['deprecationReason'] = $node->deprecationReason;
+        }
+
+        return $root;
     }
 }
diff --git a/tests/Parser/AstTest.php b/tests/Parser/AstTest.php
@@ -38,8 +38,8 @@ protected function setUp(): void
                 'enum1',
                 null,
                 [
-                    new EnumValueNode('case1', null),
-                    new EnumValueNode('case2', null),
+                    new EnumValueNode('case1', null, null),
+                    new EnumValueNode('case2', null, null),
                 ],
             ),
             $this->typeNode = new TypeNode(
@@ -53,8 +53,8 @@ protected function setUp(): void
                 'enum2',
                 null,
                 [
-                    new EnumValueNode('case3', null),
-                    new EnumValueNode('case4', null),
+                    new EnumValueNode('case3', null, null),
+                    new EnumValueNode('case4', null, null),
                 ],
             ),
             new InputTypeNode(
diff --git a/tests/Parser/NodeParser/Child/ClassFieldNodesParserTest.php b/tests/Parser/NodeParser/Child/ClassFieldNodesParserTest.php
@@ -57,6 +57,7 @@ public function itShouldParseFields(): void
                 FieldNodeType::Property,
                 null,
                 'id',
+                null,
             ),
             new FieldNode(
                 Type::createObject(DateTimeImmutable::class),
@@ -66,6 +67,7 @@ public function itShouldParseFields(): void
                 FieldNodeType::Property,
                 null,
                 'date',
+                null,
             ),
             new FieldNode(
                 Type::createScalar('string')->setNullableValue(),
@@ -75,6 +77,7 @@ public function itShouldParseFields(): void
                 FieldNodeType::Method,
                 'flow',
                 null,
+                null,
             ),
             new FieldNode(
                 Type::createScalar('string'),
@@ -84,6 +87,7 @@ public function itShouldParseFields(): void
                 FieldNodeType::Method,
                 'getStatus',
                 null,
+                null,
             ),
         ], $fields);
     }
diff --git a/tests/Parser/NodeParser/EnumNodeParserTest.php b/tests/Parser/NodeParser/EnumNodeParserTest.php
@@ -66,10 +66,10 @@ public function itShouldParseEnum(): void
             'TestEnum',
             'Test Enum',
             [
-                new EnumValueNode(TestEnumType::A->value, null),
-                new EnumValueNode(TestEnumType::B->value, null),
-                new EnumValueNode(TestEnumType::C->value, 'Case C'),
-                new EnumValueNode(TestEnumType::D->value, null),
+                new EnumValueNode(TestEnumType::A->value, null, null),
+                new EnumValueNode(TestEnumType::B->value, null, null),
+                new EnumValueNode(TestEnumType::C->value, 'Case C', null),
+                new EnumValueNode(TestEnumType::D->value, null, null),
             ],
         ), $node);
     }
diff --git a/tests/Parser/NodeParser/MutationNodeParserTest.php b/tests/Parser/NodeParser/MutationNodeParserTest.php
@@ -78,6 +78,7 @@ public function itShouldParseInputType(): void
             ],
             Type::createScalar('string'),
             '__invoke',
+            null,
         ), $node);
     }
 }
diff --git a/tests/Parser/NodeParser/QueryNodeParserTest.php b/tests/Parser/NodeParser/QueryNodeParserTest.php
@@ -78,6 +78,7 @@ public function itShouldParseInputType(): void
             ],
             Type::createScalar('string'),
             '__invoke',
+            null,
         ), $node);
     }
 }
diff --git a/tests/Parser/NodeParser/TypeNodeParserTest.php b/tests/Parser/NodeParser/TypeNodeParserTest.php
diff --git a/tests/Parser/ParserTest.php b/tests/Parser/ParserTest.php
diff --git a/tests/SchemaBuilderTest.php b/tests/SchemaBuilderTest.php
diff --git a/tests/TypeBuilder/Object/BuildArgsTraitTest.php b/tests/TypeBuilder/Object/BuildArgsTraitTest.php
diff --git a/tests/TypeBuilder/Object/EnumObjectTypeBuilderTest.php b/tests/TypeBuilder/Object/EnumObjectTypeBuilderTest.php
diff --git a/tests/TypeBuilder/Object/InputTypeObjectTypeBuilderTest.php b/tests/TypeBuilder/Object/InputTypeObjectTypeBuilderTest.php
diff --git a/tests/TypeBuilder/Object/TypeObjectTypeBuilderTest.php b/tests/TypeBuilder/Object/TypeObjectTypeBuilderTest.php
diff --git a/tests/TypeBuilder/RootTypeBuilderTest.php b/tests/TypeBuilder/RootTypeBuilderTest.php
diff --git a/tests/TypeBuilder/TypeBuilderTest.php b/tests/TypeBuilder/TypeBuilderTest.php
diff --git a/tests/TypeResolver/FieldResolverTest.php b/tests/TypeResolver/FieldResolverTest.php
diff --git a/tests/TypeResolver/RootTypeResolverTest.php b/tests/TypeResolver/RootTypeResolverTest.php

Original file line number	Diff line number	Diff line change
`@@ -11,5 +11,6 @@`
`11`	`11`	`{`
`12`	`12`	`public function __construct(`
`13`	`13`	`public ?string $description = null,`
	`14`	`+ public ?string $deprecationReason = null,`
`14`	`15`	`) {}`
`15`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,6 @@ public function __construct(`
`19`	`19`	`public FieldNodeType $fieldType,`
`20`	`20`	`public ?string $methodName,`
`21`	`21`	`public ?string $propertyName,`
	`22`	`+ public ?string $deprecationReason,`
`22`	`23`	`) {}`
`23`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -9,5 +9,6 @@`
`9`	`9`	`public function __construct(`
`10`	`10`	`public string $value,`
`11`	`11`	`public ?string $description,`
	`12`	`+ public ?string $deprecationReason,`
`12`	`13`	`) {}`
`13`	`14`	`}`