Add config options to allow fields to be updated using a setter method.

fwolfsjaeger · fwolfsjaeger · commit 5f4bcae9ceda · 2024-03-01T17:16:51.000+01:00
This change is applied in Blameable, IpTraceable, SoftDeleteable &amp; Timestampable annotations. The new attribute "setterMethod" can be passed to specify the setter method to be used for a field. If no setter method is specified, the property value would be set directly as before.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -60,6 +60,9 @@ a release.
 - Fix bug collecting metadata for inherited mapped classes
 
 ## [3.12.0] - 2023-07-08
+### Added
+- Blameable/IpTraceable/SoftDeletable/Timestampable: Added functionality to use setter method instead of setting property values directly (#2644)
+
 ### Added
 - Tree: `setSibling()` and `getSibling()` methods in the `Node` interface through the BC `@method` annotation
 - Tree: Support array of fields and directions in the `$sortByField` and `$direction` parameters at `AbstractTreeRepository::recover()`
diff --git a/src/AbstractTrackingListener.php b/src/AbstractTrackingListener.php
@@ -20,6 +20,7 @@
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\NotifyPropertyChanged;
 use Doctrine\Persistence\ObjectManager;
+use Gedmo\Exception\InvalidMappingException;
 use Gedmo\Exception\UnexpectedValueException;
 use Gedmo\Mapping\Event\AdapterInterface;
 use Gedmo\Mapping\MappedEventSubscriber;
@@ -89,7 +90,7 @@ public function onFlush(EventArgs $args)
                     $new = array_key_exists($field, $changeSet) ? $changeSet[$field][1] : false;
                     if (null === $new) { // let manual values
                         $needChanges = true;
-                        $this->updateField($object, $ea, $meta, $field);
+                        $this->updateField($object, $ea, $meta, $field, $config);
                     }
                 }
             }
@@ -101,7 +102,7 @@ public function onFlush(EventArgs $args)
                         && null === $changeSet[$field][1];
                     if (!isset($changeSet[$field]) || $isInsertAndNull) { // let manual values
                         $needChanges = true;
-                        $this->updateField($object, $ea, $meta, $field);
+                        $this->updateField($object, $ea, $meta, $field, $config);
                     }
                 }
             }
@@ -152,7 +153,7 @@ public function onFlush(EventArgs $args)
 
                             if (null === $configuredValues || ($singleField && in_array($value, $configuredValues, true))) {
                                 $needChanges = true;
-                                $this->updateField($object, $ea, $meta, $options['field']);
+                                $this->updateField($object, $ea, $meta, $options['field'], $config);
                             }
                         }
                     }
@@ -184,14 +185,14 @@ public function prePersist(EventArgs $args)
             if (isset($config['update'])) {
                 foreach ($config['update'] as $field) {
                     if (null === $meta->getReflectionProperty($field)->getValue($object)) { // let manual values
-                        $this->updateField($object, $ea, $meta, $field);
+                        $this->updateField($object, $ea, $meta, $field, $config);
                     }
                 }
             }
             if (isset($config['create'])) {
                 foreach ($config['create'] as $field) {
                     if (null === $meta->getReflectionProperty($field)->getValue($object)) { // let manual values
-                        $this->updateField($object, $ea, $meta, $field);
+                        $this->updateField($object, $ea, $meta, $field, $config);
                     }
                 }
             }
@@ -216,10 +217,11 @@ abstract protected function getFieldValue($meta, $field, $eventAdapter);
      * @param AdapterInterface $eventAdapter
      * @param ClassMetadata    $meta
      * @param string           $field
+     * @param array            $config
      *
      * @return void
      */
-    protected function updateField($object, $eventAdapter, $meta, $field)
+    protected function updateField($object, $eventAdapter, $meta, $field, array $config = [])
     {
         $property = $meta->getReflectionProperty($field);
         $oldValue = $property->getValue($object);
@@ -235,7 +237,18 @@ protected function updateField($object, $eventAdapter, $meta, $field)
             }
         }
 
-        $property->setValue($object, $newValue);
+        if (!empty($config['setterMethod'][$field])) {
+            $reflectionClass = $meta->getReflectionClass();
+            $setterName = $config['setterMethod'][$field];
+
+            if (!$reflectionClass->hasMethod($setterName)) {
+                throw new InvalidMappingException("Setter method - [{$setterName}] does not exist in class - {$meta->getName()}");
+            }
+
+            $reflectionClass->getMethod($setterName)->invoke($object, $newValue);
+        } else {
+            $property->setValue($object, $newValue);
+        }
 
         if ($object instanceof NotifyPropertyChanged) {
             $uow = $eventAdapter->getObjectManager()->getUnitOfWork();
diff --git a/src/Blameable/Mapping/Driver/Annotation.php b/src/Blameable/Mapping/Driver/Annotation.php
@@ -46,13 +46,16 @@ public function readExtendedMetadata($meta, array &$config)
         $class = $this->getMetaReflectionClass($meta);
         // property annotations
         foreach ($class->getProperties() as $property) {
-            if ($meta->isMappedSuperclass && !$property->isPrivate()
+            if (
+                isset($meta->associationMappings[$property->name]['inherited'])
+                || ($meta->isMappedSuperclass && !$property->isPrivate())
                 || $meta->isInheritedField($property->name)
-                || isset($meta->associationMappings[$property->name]['inherited'])
             ) {
                 continue;
             }
             if ($blameable = $this->reader->getPropertyAnnotation($property, self::BLAMEABLE)) {
+                assert($blameable instanceof Blameable);
+
                 $field = $property->getName();
 
                 if (!$meta->hasField($field) && !$meta->hasAssociation($field)) {
@@ -84,6 +87,8 @@ public function readExtendedMetadata($meta, array &$config)
                         'value' => $blameable->value,
                     ];
                 }
+                // add the setter method for the field
+                $this->setSetterMethod($field, $blameable->setterMethod, $config);
                 // properties are unique and mapper checks that, no risk here
                 $config[$blameable->on][] = $field;
             }
diff --git a/src/Blameable/Mapping/Driver/Xml.php b/src/Blameable/Mapping/Driver/Xml.php
@@ -63,7 +63,10 @@ public function readExtendedMetadata($meta, array &$config)
                     if (!$this->_isAttributeSet($data, 'on') || !in_array($this->_getAttribute($data, 'on'), ['update', 'create', 'change'], true)) {
                         throw new InvalidMappingException("Field - [{$field}] trigger 'on' is not one of [update, create, change] in class - {$meta->getName()}");
                     }
-
+                    if ($this->_isAttributeSet($data, 'setterMethod')) {
+                        $setterMethod = $this->_getAttribute($data, 'setterMethod');
+                        $this->setSetterMethod($field, $setterMethod, $config);
+                    }
                     if ('change' === $this->_getAttribute($data, 'on')) {
                         if (!$this->_isAttributeSet($data, 'field')) {
                             throw new InvalidMappingException("Missing parameters on property - {$field}, field must be set on [change] trigger in class - {$meta->getName()}");
diff --git a/src/Blameable/Mapping/Driver/Yaml.php b/src/Blameable/Mapping/Driver/Yaml.php
@@ -61,6 +61,10 @@ public function readExtendedMetadata($meta, array &$config)
                         throw new InvalidMappingException("Field - [{$field}] trigger 'on' is not one of [update, create, change] in class - {$meta->getName()}");
                     }
 
+                    if (isset($mappingProperty['setterMethod'])) {
+                        $this->setSetterMethod($field, $mappingProperty['setterMethod'], $config);
+                    }
+
                     if ('change' === $mappingProperty['on']) {
                         if (!isset($mappingProperty['field'])) {
                             throw new InvalidMappingException("Missing parameters on property - {$field}, field must be set on [change] trigger in class - {$meta->getName()}");
diff --git a/src/IpTraceable/Mapping/Driver/Annotation.php b/src/IpTraceable/Mapping/Driver/Annotation.php
@@ -44,13 +44,16 @@ public function readExtendedMetadata($meta, array &$config)
         $class = $this->getMetaReflectionClass($meta);
         // property annotations
         foreach ($class->getProperties() as $property) {
-            if ($meta->isMappedSuperclass && !$property->isPrivate()
-                || $meta->isInheritedField($property->name)
-                || isset($meta->associationMappings[$property->name]['inherited'])
+            if (
+                isset($meta->associationMappings[$property->name]['inherited']) ||
+                ($meta->isMappedSuperclass && !$property->isPrivate()) ||
+                $meta->isInheritedField($property->name)
             ) {
                 continue;
             }
             if ($ipTraceable = $this->reader->getPropertyAnnotation($property, self::IP_TRACEABLE)) {
+                assert($ipTraceable instanceof IpTraceable);
+
                 $field = $property->getName();
 
                 if (!$meta->hasField($field)) {
@@ -75,6 +78,8 @@ public function readExtendedMetadata($meta, array &$config)
                         'value' => $ipTraceable->value,
                     ];
                 }
+                // add the setter method for the field
+                $this->setSetterMethod($field, $ipTraceable->setterMethod, $config);
                 // properties are unique and mapper checks that, no risk here
                 $config[$ipTraceable->on][] = $field;
             }
diff --git a/src/IpTraceable/Mapping/Driver/Xml.php b/src/IpTraceable/Mapping/Driver/Xml.php
@@ -63,7 +63,10 @@ public function readExtendedMetadata($meta, array &$config)
                     if (!$this->_isAttributeSet($data, 'on') || !in_array($this->_getAttribute($data, 'on'), ['update', 'create', 'change'], true)) {
                         throw new InvalidMappingException("Field - [{$field}] trigger 'on' is not one of [update, create, change] in class - {$meta->getName()}");
                     }
-
+                    if ($this->_isAttributeSet($data, 'setterMethod')) {
+                        $setterMethod = $this->_getAttribute($data, 'setterMethod');
+                        $this->setSetterMethod($field, $setterMethod, $config);
+                    }
                     if ('change' === $this->_getAttribute($data, 'on')) {
                         if (!$this->_isAttributeSet($data, 'field')) {
                             throw new InvalidMappingException("Missing parameters on property - {$field}, field must be set on [change] trigger in class - {$meta->getName()}");
diff --git a/src/IpTraceable/Mapping/Driver/Yaml.php b/src/IpTraceable/Mapping/Driver/Yaml.php
@@ -58,6 +58,9 @@ public function readExtendedMetadata($meta, array &$config)
                     if (!isset($mappingProperty['on']) || !in_array($mappingProperty['on'], ['update', 'create', 'change'], true)) {
                         throw new InvalidMappingException("Field - [{$field}] trigger 'on' is not one of [update, create, change] in class - {$meta->getName()}");
                     }
+                    if (isset($mappingProperty['setterMethod'])) {
+                        $this->setSetterMethod($field, $mappingProperty['setterMethod'], $config);
+                    }
 
                     if ('change' === $mappingProperty['on']) {
                         if (!isset($mappingProperty['field'])) {
diff --git a/src/Mapping/Annotation/Blameable.php b/src/Mapping/Annotation/Blameable.php
@@ -34,14 +34,21 @@ final class Blameable implements GedmoAnnotation
     public $field;
     /** @var mixed */
     public $value;
+    /** @var string|null */
+    public $setterMethod;
 
     /**
      * @param array<string, mixed> $data
      * @param string|string[]|null $field
      * @param mixed                $value
      */
-    public function __construct(array $data = [], string $on = 'update', $field = null, $value = null)
-    {
+    public function __construct(
+        array $data = [],
+        string $on = 'update',
+        $field = null,
+        $value = null,
+        string $setterMethod = null
+    ) {
         if ([] !== $data) {
             Deprecation::trigger(
                 'gedmo/doctrine-extensions',
@@ -55,12 +62,14 @@ public function __construct(array $data = [], string $on = 'update', $field = nu
             $this->on = $this->getAttributeValue($data, 'on', $args, 1, $on);
             $this->field = $this->getAttributeValue($data, 'field', $args, 2, $field);
             $this->value = $this->getAttributeValue($data, 'value', $args, 3, $value);
+            $this->setterMethod = $this->getAttributeValue($data, 'setterMethod', $args, 4, $setterMethod);
 
             return;
         }
 
         $this->on = $on;
         $this->field = $field;
         $this->value = $value;
+        $this->setterMethod = $setterMethod;
     }
 }
diff --git a/src/Mapping/Annotation/IpTraceable.php b/src/Mapping/Annotation/IpTraceable.php
@@ -35,14 +35,21 @@ final class IpTraceable implements GedmoAnnotation
     public $field;
     /** @var mixed */
     public $value;
+    /** @var string|null */
+    public $setterMethod;
 
     /**
      * @param array<string, mixed> $data
      * @param string|string[]|null $field
      * @param mixed                $value
      */
-    public function __construct(array $data = [], string $on = 'update', $field = null, $value = null)
-    {
+    public function __construct(
+        array $data = [],
+        string $on = 'update',
+        $field = null,
+        $value = null,
+        string $setterMethod = null
+    ) {
         if ([] !== $data) {
             Deprecation::trigger(
                 'gedmo/doctrine-extensions',
@@ -56,12 +63,14 @@ public function __construct(array $data = [], string $on = 'update', $field = nu
             $this->on = $this->getAttributeValue($data, 'on', $args, 1, $on);
             $this->field = $this->getAttributeValue($data, 'field', $args, 2, $field);
             $this->value = $this->getAttributeValue($data, 'value', $args, 3, $value);
+            $this->setterMethod = $this->getAttributeValue($data, 'setterMethod', $args, 4, $setterMethod);
 
             return;
         }
 
         $this->on = $on;
         $this->field = $field;
         $this->value = $value;
+        $this->setterMethod = $setterMethod;
     }
 }
diff --git a/src/Mapping/Annotation/SoftDeleteable.php b/src/Mapping/Annotation/SoftDeleteable.php
@@ -35,10 +35,13 @@ final class SoftDeleteable implements GedmoAnnotation
 
     public bool $hardDelete = true;
 
+    /** @var string|null */
+    public $setterMethod;
+
     /**
      * @param array<string, mixed> $data
      */
-    public function __construct(array $data = [], string $fieldName = 'deletedAt', bool $timeAware = false, bool $hardDelete = true)
+    public function __construct(array $data = [], string $fieldName = 'deletedAt', bool $timeAware = false, bool $hardDelete = true, string $setterMethod = null)
     {
         if ([] !== $data) {
             Deprecation::trigger(
@@ -53,12 +56,14 @@ public function __construct(array $data = [], string $fieldName = 'deletedAt', b
             $this->fieldName = $this->getAttributeValue($data, 'fieldName', $args, 1, $fieldName);
             $this->timeAware = $this->getAttributeValue($data, 'timeAware', $args, 2, $timeAware);
             $this->hardDelete = $this->getAttributeValue($data, 'hardDelete', $args, 3, $hardDelete);
+            $this->setterMethod = $this->getAttributeValue($data, 'setterMethod', $args, 4, $setterMethod);
 
             return;
         }
 
         $this->fieldName = $fieldName;
         $this->timeAware = $timeAware;
         $this->hardDelete = $hardDelete;
+        $this->setterMethod = $setterMethod;
     }
 }
diff --git a/src/Mapping/Annotation/Timestampable.php b/src/Mapping/Annotation/Timestampable.php
@@ -34,14 +34,21 @@ final class Timestampable implements GedmoAnnotation
     public $field;
     /** @var mixed */
     public $value;
+    /** @var string|null */
+    public $setterMethod;
 
     /**
      * @param array<string, mixed> $data
      * @param string|string[]      $field
      * @param mixed                $value
      */
-    public function __construct(array $data = [], string $on = 'update', $field = null, $value = null)
-    {
+    public function __construct(
+        array $data = [],
+        string $on = 'update',
+        $field = null,
+        $value = null,
+        string $setterMethod = null
+    ) {
         if ([] !== $data) {
             Deprecation::trigger(
                 'gedmo/doctrine-extensions',
@@ -55,12 +62,14 @@ public function __construct(array $data = [], string $on = 'update', $field = nu
             $this->on = $this->getAttributeValue($data, 'on', $args, 1, $on);
             $this->field = $this->getAttributeValue($data, 'field', $args, 2, $field);
             $this->value = $this->getAttributeValue($data, 'value', $args, 3, $value);
+            $this->setterMethod = $this->getAttributeValue($data, 'setterMethod', $args, 4, $setterMethod);
 
             return;
         }
 
         $this->on = $on;
         $this->field = $field;
         $this->value = $value;
+        $this->setterMethod = $setterMethod;
     }
 }
diff --git a/src/Mapping/Driver/AbstractAnnotationDriver.php b/src/Mapping/Driver/AbstractAnnotationDriver.php
@@ -135,4 +135,20 @@ protected function getRelatedClassName($metadata, $name)
 
         return class_exists($className) ? $className : '';
     }
+
+    /**
+     * Set the setter method for the given field.
+     */
+    protected function setSetterMethod(string $field, ?string $method, array &$config): void
+    {
+        if (empty($method)) {
+            return;
+        }
+
+        if (!isset($config['setterMethod'])) {
+            $config['setterMethod'] = [];
+        }
+
+        $config['setterMethod'][$field] = $method;
+    }
 }
diff --git a/src/Mapping/Driver/File.php b/src/Mapping/Driver/File.php
@@ -160,4 +160,20 @@ protected function getRelatedClassName($metadata, $name)
 
         return class_exists($className) ? $className : '';
     }
+
+    /**
+     * Set the setter method for the given field.
+     */
+    protected function setSetterMethod(string $field, ?string $method, array &$config): void
+    {
+        if (empty($method)) {
+            return;
+        }
+
+        if (!isset($config['setterMethod'])) {
+            $config['setterMethod'] = [];
+        }
+
+        $config['setterMethod'][$field] = $method;
+    }
 }
diff --git a/src/SoftDeleteable/Mapping/Driver/Annotation.php b/src/SoftDeleteable/Mapping/Driver/Annotation.php
diff --git a/src/SoftDeleteable/Mapping/Driver/Xml.php b/src/SoftDeleteable/Mapping/Driver/Xml.php
diff --git a/src/SoftDeleteable/Mapping/Driver/Yaml.php b/src/SoftDeleteable/Mapping/Driver/Yaml.php
diff --git a/src/Timestampable/Mapping/Driver/Annotation.php b/src/Timestampable/Mapping/Driver/Annotation.php
diff --git a/src/Timestampable/Mapping/Driver/Xml.php b/src/Timestampable/Mapping/Driver/Xml.php
diff --git a/src/Timestampable/Mapping/Driver/Yaml.php b/src/Timestampable/Mapping/Driver/Yaml.php

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@`
`20`	`20`	`use Doctrine\Persistence\Mapping\ClassMetadata;`
`21`	`21`	`use Doctrine\Persistence\NotifyPropertyChanged;`
`22`	`22`	`use Doctrine\Persistence\ObjectManager;`
	`23`	`+use Gedmo\Exception\InvalidMappingException;`
`23`	`24`	`use Gedmo\Exception\UnexpectedValueException;`
`24`	`25`	`use Gedmo\Mapping\Event\AdapterInterface;`
`25`	`26`	`use Gedmo\Mapping\MappedEventSubscriber;`
`@@ -89,7 +90,7 @@ public function onFlush(EventArgs $args)`
`89`	`90`	`$new = array_key_exists($field, $changeSet) ? $changeSet[$field][1] : false;`
`90`	`91`	`if (null === $new) { // let manual values`
`91`	`92`	`$needChanges = true;`
`92`		`- $this->updateField($object, $ea, $meta, $field);`
	`93`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`93`	`94`	`}`
`94`	`95`	`}`
`95`	`96`	`}`
`@@ -101,7 +102,7 @@ public function onFlush(EventArgs $args)`
`101`	`102`	`&& null === $changeSet[$field][1];`
`102`	`103`	`if (!isset($changeSet[$field]) \|\| $isInsertAndNull) { // let manual values`
`103`	`104`	`$needChanges = true;`
`104`		`- $this->updateField($object, $ea, $meta, $field);`
	`105`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`105`	`106`	`}`
`106`	`107`	`}`
`107`	`108`	`}`
`@@ -152,7 +153,7 @@ public function onFlush(EventArgs $args)`
`152`	`153`
`153`	`154`	`if (null === $configuredValues \|\| ($singleField && in_array($value, $configuredValues, true))) {`
`154`	`155`	`$needChanges = true;`
`155`		`- $this->updateField($object, $ea, $meta, $options['field']);`
	`156`	`+ $this->updateField($object, $ea, $meta, $options['field'], $config);`
`156`	`157`	`}`
`157`	`158`	`}`
`158`	`159`	`}`
`@@ -184,14 +185,14 @@ public function prePersist(EventArgs $args)`
`184`	`185`	`if (isset($config['update'])) {`
`185`	`186`	`foreach ($config['update'] as $field) {`
`186`	`187`	`if (null === $meta->getReflectionProperty($field)->getValue($object)) { // let manual values`
`187`		`- $this->updateField($object, $ea, $meta, $field);`
	`188`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`188`	`189`	`}`
`189`	`190`	`}`
`190`	`191`	`}`
`191`	`192`	`if (isset($config['create'])) {`
`192`	`193`	`foreach ($config['create'] as $field) {`
`193`	`194`	`if (null === $meta->getReflectionProperty($field)->getValue($object)) { // let manual values`
`194`		`- $this->updateField($object, $ea, $meta, $field);`
	`195`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`195`	`196`	`}`
`196`	`197`	`}`
`197`	`198`	`}`
`@@ -216,10 +217,11 @@ abstract protected function getFieldValue($meta, $field, $eventAdapter);`
`216`	`217`	`* @param AdapterInterface $eventAdapter`
`217`	`218`	`* @param ClassMetadata $meta`
`218`	`219`	`* @param string $field`
	`220`	`+ * @param array $config`
`219`	`221`	`*`
`220`	`222`	`* @return void`
`221`	`223`	`*/`
`222`		`- protected function updateField($object, $eventAdapter, $meta, $field)`
	`224`	`+ protected function updateField($object, $eventAdapter, $meta, $field, array $config = [])`
`223`	`225`	`{`
`224`	`226`	`$property = $meta->getReflectionProperty($field);`
`225`	`227`	`$oldValue = $property->getValue($object);`
`@@ -235,7 +237,18 @@ protected function updateField($object, $eventAdapter, $meta, $field)`
`235`	`237`	`}`
`236`	`238`	`}`
`237`	`239`
`238`		`- $property->setValue($object, $newValue);`
	`240`	`+ if (!empty($config['setterMethod'][$field])) {`
	`241`	`+ $reflectionClass = $meta->getReflectionClass();`
	`242`	`+ $setterName = $config['setterMethod'][$field];`
	`243`	`+`
	`244`	`+ if (!$reflectionClass->hasMethod($setterName)) {`
	`245`	`+ throw new InvalidMappingException("Setter method - [{$setterName}] does not exist in class - {$meta->getName()}");`
	`246`	`+ }`
	`247`	`+`
	`248`	`+ $reflectionClass->getMethod($setterName)->invoke($object, $newValue);`
	`249`	`+ } else {`
	`250`	`+ $property->setValue($object, $newValue);`
	`251`	`+ }`
`239`	`252`
`240`	`253`	`if ($object instanceof NotifyPropertyChanged) {`
`241`	`254`	`$uow = $eventAdapter->getObjectManager()->getUnitOfWork();`
Original file line number	Diff line number	Diff line change
`@@ -58,6 +58,9 @@ public function readExtendedMetadata($meta, array &$config)`
`58`	`58`	`if (!isset($mappingProperty['on']) \|\| !in_array($mappingProperty['on'], ['update', 'create', 'change'], true)) {`
`59`	`59`	`throw new InvalidMappingException("Field - [{$field}] trigger 'on' is not one of [update, create, change] in class - {$meta->getName()}");`
`60`	`60`	`}`
	`61`	`+ if (isset($mappingProperty['setterMethod'])) {`
	`62`	`+ $this->setSetterMethod($field, $mappingProperty['setterMethod'], $config);`
	`63`	`+ }`
`61`	`64`
`62`	`65`	`if ('change' === $mappingProperty['on']) {`
`63`	`66`	`if (!isset($mappingProperty['field'])) {`