[DoctrineBridge] Add comparator option to UniqueEntity constraint and enforce use of only identifierFieldNames or comparator

Stephan Six · Stephan Six · commit 07bfc5f01d37 · 2025-07-24T11:18:19.000+02:00
The `comparator` allows the `UniqueEntityValidator` to delegate the equality check to a user-defined callback. This helps in edge-cases where a simple equality check (after casting to string) of all `identifierFieldNames` is not enough.
diff --git a/src/Symfony/Bridge/Doctrine/Tests/Validator/Constraints/UniqueEntityTest.php b/src/Symfony/Bridge/Doctrine/Tests/Validator/Constraints/UniqueEntityTest.php
@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
+use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 use Symfony\Component\Validator\Mapping\Loader\AttributeLoader;
 
@@ -70,6 +71,18 @@ public function testValueOptionConfiguresFields()
 
         $this->assertSame('email', $constraint->fields);
     }
+
+    public function testOnlyOneOfIdentifierFielsOrComparatorAreAllowed()
+    {
+        $this->expectException(ConstraintDefinitionException::class);
+        $this->expectExceptionMessage('Only "identifierFieldNames" or "comparator" can be used at the same time.');
+
+        new UniqueEntity(
+            fields: ['field'],
+            identifierFieldNames: ['identifier'],
+            comparator: function () {},
+        );
+    }
 }
 
 #[UniqueEntity(['email'], message: 'myMessage')]
diff --git a/src/Symfony/Bridge/Doctrine/Tests/Validator/Constraints/UniqueEntityValidatorTest.php b/src/Symfony/Bridge/Doctrine/Tests/Validator/Constraints/UniqueEntityValidatorTest.php
@@ -1448,4 +1448,41 @@ public function testUuidIdentifierWithSameValueDifferentInstanceDoesNotCauseViol
 
         $this->assertNoViolation();
     }
+
+    public function testCheckForUniquenessIsDelegatedToComparator()
+    {
+        $comparatorAsBeenCalled = false;
+
+        $entity = new Person(1, 'Foo');
+
+        $this->em->persist($entity);
+        $this->em->flush();
+
+        $dto = new UpdateEmployeeProfile(2, 'Foo');
+
+        $constraint = new UniqueEntity(
+            fields: ['name'],
+            message: 'myMessage',
+            em: self::EM_NAME,
+            entityClass: Person::class,
+            comparator: function ($value, $foundEntity) use ($dto, $entity, &$comparatorAsBeenCalled) {
+                $comparatorAsBeenCalled = true;
+
+                $this->assertSame($value, $dto);
+                $this->assertSame($foundEntity, $entity);
+
+                // Usually, using `'identifierFieldNames' => ['id'],` would fail validation
+                // because the ids don't match. The comparator specifically allows for
+                // overwriting this behavior.
+
+                return true;
+            },
+        );
+
+        $this->validator->validate($dto, $constraint);
+
+        $this->assertTrue($comparatorAsBeenCalled);
+
+        $this->assertNoViolation();
+    }
 }
diff --git a/src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntity.php b/src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntity.php
@@ -13,6 +13,7 @@
 
 use Symfony\Component\Validator\Attribute\HasNamedArguments;
 use Symfony\Component\Validator\Constraint;
+use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
 
 /**
  * Constraint for the Unique Entity validator.
@@ -37,6 +38,7 @@ class UniqueEntity extends Constraint
     public ?string $errorPath = null;
     public bool|array|string $ignoreNull = true;
     public array $identifierFieldNames = [];
+    public ?\Closure $comparator = null;
 
     /**
      * @param array|string         $fields           The combination of fields that must contain unique values or a set of options
@@ -46,6 +48,9 @@ class UniqueEntity extends Constraint
      * @param string|null          $repositoryMethod The repository method to check uniqueness instead of findBy. The method will receive as its argument
      *                                               a fieldName => value associative array according to the fields option configuration
      * @param string|null          $errorPath        Bind the constraint violation to this field instead of the first one in the fields option configuration
+     * @param callable|null        $comparator       A custom callback to check the uniqueness of the found entity. The first parameter will
+     *                                               be the object this constraint is applied to, the second parameter will be the found entity. The callback
+     *                                               should return true if both are considered to be the same.
      */
     #[HasNamedArguments]
     public function __construct(
@@ -58,6 +63,7 @@ public function __construct(
         ?string $errorPath = null,
         bool|string|array|null $ignoreNull = null,
         ?array $identifierFieldNames = null,
+        ?callable $comparator = null,
         ?array $groups = null,
         $payload = null,
         ?array $options = null,
@@ -89,6 +95,11 @@ public function __construct(
         $this->errorPath = $errorPath ?? $this->errorPath;
         $this->ignoreNull = $ignoreNull ?? $this->ignoreNull;
         $this->identifierFieldNames = $identifierFieldNames ?? $this->identifierFieldNames;
+        $this->comparator = $comparator === null ? $this->comparator : $comparator(...);
+
+        if ($this->identifierFieldNames !== [] && $this->comparator !== null) {
+            throw new ConstraintDefinitionException('Only "identifierFieldNames" or "comparator" can be used at the same time.');
+        }
     }
 
     /**
diff --git a/src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntityValidator.php b/src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntityValidator.php
@@ -186,29 +186,33 @@ public function validate(mixed $value, Constraint $constraint): void
         /* If a single entity matched the query criteria, which is the same as
          * the entity being updated by validated object, the criteria is unique.
          */
-        if (!$isValueEntity && !empty($constraint->identifierFieldNames) && 1 === \count($result)) {
-            $fieldValues = $this->getFieldValues($value, $class, $constraint->identifierFieldNames);
-            if (array_values($class->getIdentifierFieldNames()) != array_values($constraint->identifierFieldNames)) {
-                throw new ConstraintDefinitionException(\sprintf('The "%s" entity identifier field names should be "%s", not "%s".', $entityClass, implode(', ', $class->getIdentifierFieldNames()), implode(', ', $constraint->identifierFieldNames)));
-            }
-
-            $entityMatched = true;
-
-            foreach ($constraint->identifierFieldNames as $identifierFieldName) {
-                $propertyValue = $this->getPropertyValue($entityClass, $identifierFieldName, current($result));
-                if ($fieldValues[$identifierFieldName] instanceof \Stringable) {
-                    $fieldValues[$identifierFieldName] = (string) $fieldValues[$identifierFieldName];
-                }
-                if ($propertyValue instanceof \Stringable) {
-                    $propertyValue = (string) $propertyValue;
+        if (!$isValueEntity && 1 === \count($result)) {
+            if (!empty($constraint->identifierFieldNames)) {
+                $fieldValues = $this->getFieldValues($value, $class, $constraint->identifierFieldNames);
+                if (array_values($class->getIdentifierFieldNames()) != array_values($constraint->identifierFieldNames)) {
+                    throw new ConstraintDefinitionException(\sprintf('The "%s" entity identifier field names should be "%s", not "%s".', $entityClass, implode(', ', $class->getIdentifierFieldNames()), implode(', ', $constraint->identifierFieldNames)));
                 }
-                if ($fieldValues[$identifierFieldName] !== $propertyValue) {
-                    $entityMatched = false;
-                    break;
+
+                $entityMatched = true;
+
+                foreach ($constraint->identifierFieldNames as $identifierFieldName) {
+                    $propertyValue = $this->getPropertyValue($entityClass, $identifierFieldName, current($result));
+                    if ($fieldValues[$identifierFieldName] instanceof \Stringable) {
+                        $fieldValues[$identifierFieldName] = (string) $fieldValues[$identifierFieldName];
+                    }
+                    if ($propertyValue instanceof \Stringable) {
+                        $propertyValue = (string) $propertyValue;
+                    }
+                    if ($fieldValues[$identifierFieldName] !== $propertyValue) {
+                        $entityMatched = false;
+                        break;
+                    }
                 }
-            }
 
-            if ($entityMatched) {
+                if ($entityMatched) {
+                    return;
+                }
+            } elseif (!empty($constraint->comparator) && ($constraint->comparator)($value, current($result))) {
                 return;
             }
         }
