Deprecate update flag, update the docs

Author: oprypkhantc

src/Annotations/Input.php

@@ -7,6 +7,10 @@
 use Attribute;
 use RuntimeException;
 
+use function array_key_exists;
+
+use const E_USER_DEPRECATED;
+
 /**
  * The Input attribute must be put in a GraphQL input type class docblock and is used to map to the underlying PHP class
  * this is exposed via this input type.
@@ -33,6 +37,14 @@ public function __construct(
         string|null $description = null,
         bool|null $update = null,
     ) {
+        if ($update !== null || array_key_exists('update', $attributes)) {
+            trigger_error(
+                'Using #[Input(update: ...)] is deprecated and will be removed in a future major version. '
+                . 'For partial updates, prefer nullable fields with Undefined to distinguish omitted values from explicit nulls.',
+                E_USER_DEPRECATED,
+            );
+        }
+
         $this->name = $name ?? $attributes['name'] ?? null;
         $this->default = $default ?? $attributes['default'] ?? $this->name === null;
         $this->description = $description ?? $attributes['description'] ?? null;
@@ -86,6 +98,8 @@ public function getDescription(): string|null
     /**
      * Returns true if this type should behave as update resource.
      * Such input type has all fields optional and without default value in the documentation.
+     *
+     * @deprecated Using #[Input(update: ...)] is deprecated; prefer nullable fields with Undefined.
      */
     public function isUpdate(): bool
     {

tests/Annotations/InputTest.php

@@ -15,4 +15,11 @@ public function testException(): void
         $this->expectExceptionMessage('Empty class for #[Input] attribute. You MUST create the Input attribute object using the GraphQLite AnnotationReader');
         (new Input())->getClass();
     }
+
+    public function testUpdateArgumentTriggersDeprecation(): void
+    {
+        $this->expectUserDeprecationMessageMatches('/Using #\[Input\(update: \.\.\.\)\] is deprecated/');
+
+        new Input(update: true);
+    }
 }

website/docs/attributes-reference.md

@@ -178,7 +178,7 @@ Attribute      | Compulsory | Type   | Definition
 name           | *no*       | string | The name of the GraphQL input type generated. If not passed, the name of the class with suffix "Input" is used. If the class ends with "Input", the "Input" suffix is not added.
 description    | *no*       | string | Description of the input type in the documentation. If not passed, PHP doc comment is used.
 default        | *no*       | bool   | Name of the input type represented in your GraphQL schema. Defaults to `true` *only if* the name is not specified. If `name` is specified, this will default to `false`, so must also be included for `true` when `name` is used.
-update         | *no*       | bool   | Determines if the the input represents a partial update. When set to `true` all input fields will become optional and won't have default values thus won't be set on resolve if they are not specified in the query/mutation/subscription.  This primarily applies to nullable fields.
+update         | *no*       | bool   | Deprecated. `#[Input(update: true)]` still works for compatibility, but for partial updates you should prefer nullable fields with `Undefined` so omitted values can be distinguished from explicit `null`.
 
 ## #[Logged]
 

website/docs/input-types.mdx

@@ -151,11 +151,8 @@ There are 2 input types added to the `UserInput` class: `CreateUserInput` and `U
 - Field `password` will appear for both. For `CreateUserInput` it'll be the required field and for `UpdateUserInput` optional.
 - Field `age` is optional for both input types.
 
-Note that `update: true` argument for `UpdateUserInput`. It should be used when input type is used for a partial update,
-It makes all fields optional and removes all default values from thus prevents setting default values via setters or directly to public properties.
-In example above if you use the class as `UpdateUserInput` and set only `username` the other ones will be ignored.
-In PHP 7 they will be set to `null`, while in PHP 8 they will be in not initialized state - this can be used as a trick
-to check if user actually passed a value for a certain field.
+`update: true` is deprecated and will be removed in a future major version.
+For partial updates, prefer nullable fields with `Undefined` so you can distinguish omitted values from explicit `null`.
 
 ### Optional input fields
 
@@ -201,12 +198,24 @@ class Article
 	public function title(string|null|Undefined $locale): string
     {
         if ($locale === Undefined::VALUE) {
-            return
+            return $this->title;
         }
+
+        if ($locale === null) {
+            throw new InvalidArgumentException('Locale cannot be null.');
+        }
+
+        return $this->translateTitle($locale);
     }
 }
 ```
 
+For field parameters and input field properties, an explicit `= Undefined::VALUE` default is not required:
+when the type includes `Undefined`, GraphQLite resolves omitted values as `Undefined::VALUE`. Adding the
+default explicitly is optional and can still be useful for clarity. Constructor parameters and promoted
+properties are different: if you want an omitted value there to resolve to `Undefined::VALUE`, you still
+need a real PHP default such as `= Undefined::VALUE`.
+
 ## Factory
 
 A **Factory** is a method that takes in parameter all the fields of the input type and return an object.