Specify identifying columns on nested mutation upserts

CHANGELOG.md

@@ -9,6 +9,10 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+### Added
+
+- Specify identifying columns on nested mutation upserts with `@upsert` and `@upsertMany` https://github.com/nuwave/lighthouse/pull/2426
+
 ## v6.64.3
 
 ### Fixed

docs/master/api-reference/directives.md

@@ -4024,6 +4024,12 @@ directive @upsert(
   """
   model: String
 
+  """
+  Specify the columns by which to upsert the model.
+  Optional, by default `id` or the primary key of the model are used.
+  """
+  identifyingColumns: [String!]
+
   """
   Specify the name of the relation on the parent model.
   This is only needed when using this directive as a nested arg
@@ -4043,6 +4049,16 @@ type Mutation {
 }
 ```
 
+When you pass `identifyingColumns`, Lighthouse will first try to match an existing model through those columns and only then fall back to `id`.
+All configured identifying columns must be present with non-null values, otherwise the upsert fails with a GraphQL error.
+
+```graphql
+type Mutation {
+  upsertUser(email: String!, name: String!): User!
+    @upsert(identifyingColumns: ["email"])
+}
+```
+
 This directive can also be used as a [nested arg resolver](../concepts/arg-resolvers.md).
 
 ## @upsertMany
@@ -4058,6 +4074,12 @@ directive @upsertMany(
   """
   model: String
 
+  """
+  Specify the columns by which to upsert the model.
+  Optional, by default `id` or the primary key of the model are used.
+  """
+  identifyingColumns: [String!]
+
   """
   Specify the name of the relation on the parent model.
   This is only needed when using this directive as a nested arg
@@ -4080,6 +4102,22 @@ input UpsertPostInput {
 }
 ```
 
+You can also use `identifyingColumns` with `@upsertMany`:
+
+```graphql
+type Mutation {
+  upsertUsers(inputs: [UpsertUserInput!]!): [User!]!
+    @upsertMany(identifyingColumns: ["email"])
+}
+
+input UpsertUserInput {
+  email: String!
+  name: String!
+}
+```
+
+For `@upsertMany`, all configured identifying columns must be present with non-null values for every input item, otherwise the upsert fails with a GraphQL error.
+
 ## @validator
 
 ```graphql

docs/master/eloquent/getting-started.md

@@ -260,6 +260,17 @@ type Mutation {
 }
 ```
 
+If you want to identify records by custom fields, pass `identifyingColumns`:
+
+```graphql
+type Mutation {
+  upsertUser(name: String!, email: String!): User!
+    @upsert(identifyingColumns: ["email"])
+}
+```
+
+When using `identifyingColumns`, all configured identifying columns must be provided with non-null values, otherwise the upsert fails with a GraphQL error.
+
 Since upsert can create or update your data, your input should mark the minimum required fields as non-nullable.
 
 ```graphql

src/Execution/Arguments/UpsertModel.php

@@ -2,17 +2,25 @@
 
 namespace Nuwave\Lighthouse\Execution\Arguments;
 
+use GraphQL\Error\Error;
 use Illuminate\Database\Eloquent\Model;
 use Nuwave\Lighthouse\Support\Contracts\ArgResolver;
 
+use function Safe\array_flip;
+
 class UpsertModel implements ArgResolver
 {
+    public const MISSING_IDENTIFYING_COLUMNS_FOR_UPSERT = 'All configured identifying columns must be present and non-null for upsert.';
+
     /** @var callable|\Nuwave\Lighthouse\Support\Contracts\ArgResolver */
     protected $previous;
 
     /** @param  callable|\Nuwave\Lighthouse\Support\Contracts\ArgResolver  $previous */
-    public function __construct(callable $previous)
-    {
+    public function __construct(
+        callable $previous,
+        /** @var array<string>|null */
+        protected ?array $identifyingColumns = null,
+    ) {
         $this->previous = $previous;
     }
 
@@ -22,21 +30,58 @@ public function __construct(callable $previous)
      */
     public function __invoke($model, $args): mixed
     {
-        // TODO consider Laravel native ->upsert(), available from 8.10
+        // Do not use Laravel native upsert() here, as it bypasses model hydration and model events.
+        $existingModel = null;
 
-        $id = $this->retrieveID($model, $args);
-        if ($id) {
-            $existingModel = $model->newQuery()
-                ->find($id);
+        if ($this->identifyingColumns) {
+            $identifyingColumns = $this->identifyingColumnValues($args, $this->identifyingColumns)
+                ?? throw new Error(self::MISSING_IDENTIFYING_COLUMNS_FOR_UPSERT);
+
+            $existingModel = $model->newQuery()->firstWhere($identifyingColumns);
 
             if ($existingModel !== null) {
                 $model = $existingModel;
             }
         }
 
+        if ($existingModel === null) {
+            $id = $this->retrieveID($model, $args);
+            if ($id) {
+                $existingModel = $model->newQuery()->find($id);
+                if ($existingModel !== null) {
+                    $model = $existingModel;
+                }
+            }
+        }
+
         return ($this->previous)($model, $args);
     }
 
+    /**
+     * @param  array<int, string>  $identifyingColumns
+     *
+     * @return array<string, mixed>|null
+     */
+    protected function identifyingColumnValues(ArgumentSet $args, array $identifyingColumns): ?array
+    {
+        $identifyingValues = array_intersect_key(
+            $args->toArray(),
+            array_flip($identifyingColumns),
+        );
+
+        if (count($identifyingValues) !== count($identifyingColumns)) {
+            return null;
+        }
+
+        foreach ($identifyingValues as $identifyingValue) {
+            if ($identifyingValue === null) {
+                return null;
+            }
+        }
+
+        return $identifyingValues;
+    }
+
     /** @return mixed The value of the ID or null */
     protected function retrieveID(Model $model, ArgumentSet $args)
     {

src/Schema/Directives/UpsertDirective.php

@@ -2,11 +2,21 @@
 
 namespace Nuwave\Lighthouse\Schema\Directives;
 
+use GraphQL\Language\AST\FieldDefinitionNode;
+use GraphQL\Language\AST\InputObjectTypeDefinitionNode;
+use GraphQL\Language\AST\InputValueDefinitionNode;
+use GraphQL\Language\AST\InterfaceTypeDefinitionNode;
+use GraphQL\Language\AST\ObjectTypeDefinitionNode;
 use Illuminate\Database\Eloquent\Relations\Relation;
+use Nuwave\Lighthouse\Exceptions\DefinitionException;
 use Nuwave\Lighthouse\Execution\Arguments\SaveModel;
 use Nuwave\Lighthouse\Execution\Arguments\UpsertModel;
+use Nuwave\Lighthouse\Schema\AST\DocumentAST;
+use Nuwave\Lighthouse\Support\Contracts\ArgManipulator;
+use Nuwave\Lighthouse\Support\Contracts\FieldManipulator;
+use Nuwave\Lighthouse\Support\Contracts\InputFieldManipulator;
 
-class UpsertDirective extends OneModelMutationDirective
+class UpsertDirective extends OneModelMutationDirective implements ArgManipulator, FieldManipulator, InputFieldManipulator
 {
     public static function definition(): string
     {
@@ -21,6 +31,12 @@ public static function definition(): string
   """
   model: String
 
+  """
+  Specify the columns by which to upsert the model.
+  Optional, by default `id` or the primary key of the model are used.
+  """
+  identifyingColumns: [String!]
+
   """
   Specify the name of the relation on the parent model.
   This is only needed when using this directive as a nested arg
@@ -33,6 +49,43 @@ public static function definition(): string
 
     protected function makeExecutionFunction(?Relation $parentRelation = null): callable
     {
-        return new UpsertModel(new SaveModel($parentRelation));
+        return new UpsertModel(
+            new SaveModel($parentRelation),
+            $this->directiveArgValue('identifyingColumns'),
+        );
+    }
+
+    public function manipulateArgDefinition(
+        DocumentAST &$documentAST,
+        InputValueDefinitionNode &$argDefinition,
+        FieldDefinitionNode &$parentField,
+        ObjectTypeDefinitionNode|InterfaceTypeDefinitionNode &$parentType,
+    ): void {
+        $this->ensureNonEmptyIdentifyingColumns("{$parentType->name->value}.{$parentField->name->value}:{$argDefinition->name->value}");
+    }
+
+    public function manipulateFieldDefinition(
+        DocumentAST &$documentAST,
+        FieldDefinitionNode &$fieldDefinition,
+        ObjectTypeDefinitionNode|InterfaceTypeDefinitionNode &$parentType,
+    ): void {
+        $this->ensureNonEmptyIdentifyingColumns("{$parentType->name->value}.{$fieldDefinition->name->value}");
+    }
+
+    public function manipulateInputFieldDefinition(
+        DocumentAST &$documentAST,
+        InputValueDefinitionNode &$inputField,
+        InputObjectTypeDefinitionNode &$parentInput,
+    ): void {
+        $this->ensureNonEmptyIdentifyingColumns("{$parentInput->name->value}.{$inputField->name->value}");
+    }
+
+    protected function ensureNonEmptyIdentifyingColumns(string $location): void
+    {
+        $identifyingColumns = $this->directiveArgValue('identifyingColumns');
+
+        if ($identifyingColumns === []) {
+            throw new DefinitionException("Must specify non-empty list of columns in `identifyingColumns` argument of `@{$this->name()}` directive on `{$location}`.");
+        }
     }
 }

src/Schema/Directives/UpsertManyDirective.php

@@ -2,11 +2,21 @@
 
 namespace Nuwave\Lighthouse\Schema\Directives;
 
+use GraphQL\Language\AST\FieldDefinitionNode;
+use GraphQL\Language\AST\InputObjectTypeDefinitionNode;
+use GraphQL\Language\AST\InputValueDefinitionNode;
+use GraphQL\Language\AST\InterfaceTypeDefinitionNode;
+use GraphQL\Language\AST\ObjectTypeDefinitionNode;
 use Illuminate\Database\Eloquent\Relations\Relation;
+use Nuwave\Lighthouse\Exceptions\DefinitionException;
 use Nuwave\Lighthouse\Execution\Arguments\SaveModel;
 use Nuwave\Lighthouse\Execution\Arguments\UpsertModel;
+use Nuwave\Lighthouse\Schema\AST\DocumentAST;
+use Nuwave\Lighthouse\Support\Contracts\ArgManipulator;
+use Nuwave\Lighthouse\Support\Contracts\FieldManipulator;
+use Nuwave\Lighthouse\Support\Contracts\InputFieldManipulator;
 
-class UpsertManyDirective extends ManyModelMutationDirective
+class UpsertManyDirective extends ManyModelMutationDirective implements ArgManipulator, FieldManipulator, InputFieldManipulator
 {
     public static function definition(): string
     {
@@ -21,6 +31,12 @@ public static function definition(): string
   """
   model: String
 
+  """
+  Specify the columns by which to upsert the model.
+  Optional, by default `id` or the primary key of the model are used.
+  """
+  identifyingColumns: [String!]
+
   """
   Specify the name of the relation on the parent model.
   This is only needed when using this directive as a nested arg
@@ -33,6 +49,43 @@ public static function definition(): string
 
     protected function makeExecutionFunction(?Relation $parentRelation = null): callable
     {
-        return new UpsertModel(new SaveModel($parentRelation));
+        return new UpsertModel(
+            new SaveModel($parentRelation),
+            $this->directiveArgValue('identifyingColumns'),
+        );
+    }
+
+    public function manipulateArgDefinition(
+        DocumentAST &$documentAST,
+        InputValueDefinitionNode &$argDefinition,
+        FieldDefinitionNode &$parentField,
+        ObjectTypeDefinitionNode|InterfaceTypeDefinitionNode &$parentType,
+    ): void {
+        $this->ensureNonEmptyIdentifyingColumns("{$parentType->name->value}.{$parentField->name->value}:{$argDefinition->name->value}");
+    }
+
+    public function manipulateFieldDefinition(
+        DocumentAST &$documentAST,
+        FieldDefinitionNode &$fieldDefinition,
+        ObjectTypeDefinitionNode|InterfaceTypeDefinitionNode &$parentType,
+    ): void {
+        $this->ensureNonEmptyIdentifyingColumns("{$parentType->name->value}.{$fieldDefinition->name->value}");
+    }
+
+    public function manipulateInputFieldDefinition(
+        DocumentAST &$documentAST,
+        InputValueDefinitionNode &$inputField,
+        InputObjectTypeDefinitionNode &$parentInput,
+    ): void {
+        $this->ensureNonEmptyIdentifyingColumns("{$parentInput->name->value}.{$inputField->name->value}");
+    }
+
+    protected function ensureNonEmptyIdentifyingColumns(string $location): void
+    {
+        $identifyingColumns = $this->directiveArgValue('identifyingColumns');
+
+        if ($identifyingColumns === []) {
+            throw new DefinitionException("Must specify non-empty list of columns in `identifyingColumns` argument of `@{$this->name()}` directive on `{$location}`.");
+        }
     }
 }