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

fwolfsjaeger · fwolfsjaeger · commit f8ac1484ce74 · 2023-12-01T14:33:44.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
@@ -36,6 +36,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
@@ -18,6 +18,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;
@@ -83,7 +84,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);
                     }
                 }
             }
@@ -95,7 +96,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);
                     }
                 }
             }
@@ -146,7 +147,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);
                             }
                         }
                     }
@@ -174,14 +175,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);
                     }
                 }
             }
@@ -206,10 +207,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);
@@ -225,7 +227,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
@@ -33,14 +33,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) {
             @trigger_error(sprintf(
                 'Passing an array as first argument to "%s()" is deprecated. Use named arguments instead.',
@@ -52,12 +59,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
@@ -34,14 +34,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) {
             @trigger_error(sprintf(
                 'Passing an array as first argument to "%s()" is deprecated. Use named arguments instead.',
@@ -53,12 +60,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
@@ -34,10 +34,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) {
             @trigger_error(sprintf(
@@ -50,12 +53,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
@@ -33,14 +33,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) {
             @trigger_error(sprintf(
                 'Passing an array as first argument to "%s()" is deprecated. Use named arguments instead.',
@@ -52,12 +59,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
@@ -134,4 +134,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
`@@ -18,6 +18,7 @@`
`18`	`18`	`use Doctrine\Persistence\Mapping\ClassMetadata;`
`19`	`19`	`use Doctrine\Persistence\NotifyPropertyChanged;`
`20`	`20`	`use Doctrine\Persistence\ObjectManager;`
	`21`	`+use Gedmo\Exception\InvalidMappingException;`
`21`	`22`	`use Gedmo\Exception\UnexpectedValueException;`
`22`	`23`	`use Gedmo\Mapping\Event\AdapterInterface;`
`23`	`24`	`use Gedmo\Mapping\MappedEventSubscriber;`
`@@ -83,7 +84,7 @@ public function onFlush(EventArgs $args)`
`83`	`84`	`$new = array_key_exists($field, $changeSet) ? $changeSet[$field][1] : false;`
`84`	`85`	`if (null === $new) { // let manual values`
`85`	`86`	`$needChanges = true;`
`86`		`- $this->updateField($object, $ea, $meta, $field);`
	`87`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`87`	`88`	`}`
`88`	`89`	`}`
`89`	`90`	`}`
`@@ -95,7 +96,7 @@ public function onFlush(EventArgs $args)`
`95`	`96`	`&& null === $changeSet[$field][1];`
`96`	`97`	`if (!isset($changeSet[$field]) \|\| $isInsertAndNull) { // let manual values`
`97`	`98`	`$needChanges = true;`
`98`		`- $this->updateField($object, $ea, $meta, $field);`
	`99`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`99`	`100`	`}`
`100`	`101`	`}`
`101`	`102`	`}`
`@@ -146,7 +147,7 @@ public function onFlush(EventArgs $args)`
`146`	`147`
`147`	`148`	`if (null === $configuredValues \|\| ($singleField && in_array($value, $configuredValues, true))) {`
`148`	`149`	`$needChanges = true;`
`149`		`- $this->updateField($object, $ea, $meta, $options['field']);`
	`150`	`+ $this->updateField($object, $ea, $meta, $options['field'], $config);`
`150`	`151`	`}`
`151`	`152`	`}`
`152`	`153`	`}`
`@@ -174,14 +175,14 @@ public function prePersist(EventArgs $args)`
`174`	`175`	`if (isset($config['update'])) {`
`175`	`176`	`foreach ($config['update'] as $field) {`
`176`	`177`	`if (null === $meta->getReflectionProperty($field)->getValue($object)) { // let manual values`
`177`		`- $this->updateField($object, $ea, $meta, $field);`
	`178`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`178`	`179`	`}`
`179`	`180`	`}`
`180`	`181`	`}`
`181`	`182`	`if (isset($config['create'])) {`
`182`	`183`	`foreach ($config['create'] as $field) {`
`183`	`184`	`if (null === $meta->getReflectionProperty($field)->getValue($object)) { // let manual values`
`184`		`- $this->updateField($object, $ea, $meta, $field);`
	`185`	`+ $this->updateField($object, $ea, $meta, $field, $config);`
`185`	`186`	`}`
`186`	`187`	`}`
`187`	`188`	`}`
`@@ -206,10 +207,11 @@ abstract protected function getFieldValue($meta, $field, $eventAdapter);`
`206`	`207`	`* @param AdapterInterface $eventAdapter`
`207`	`208`	`* @param ClassMetadata $meta`
`208`	`209`	`* @param string $field`
	`210`	`+ * @param array $config`
`209`	`211`	`*`
`210`	`212`	`* @return void`
`211`	`213`	`*/`
`212`		`- protected function updateField($object, $eventAdapter, $meta, $field)`
	`214`	`+ protected function updateField($object, $eventAdapter, $meta, $field, array $config = [])`
`213`	`215`	`{`
`214`	`216`	`$property = $meta->getReflectionProperty($field);`
`215`	`217`	`$oldValue = $property->getValue($object);`
`@@ -225,7 +227,18 @@ protected function updateField($object, $eventAdapter, $meta, $field)`
`225`	`227`	`}`
`226`	`228`	`}`
`227`	`229`
`228`		`- $property->setValue($object, $newValue);`
	`230`	`+ if (!empty($config['setterMethod'][$field])) {`
	`231`	`+ $reflectionClass = $meta->getReflectionClass();`
	`232`	`+ $setterName = $config['setterMethod'][$field];`
	`233`	`+`
	`234`	`+ if (!$reflectionClass->hasMethod($setterName)) {`
	`235`	`+ throw new InvalidMappingException("Setter method - [{$setterName}] does not exist in class - {$meta->getName()}");`
	`236`	`+ }`
	`237`	`+`
	`238`	`+ $reflectionClass->getMethod($setterName)->invoke($object, $newValue);`
	`239`	`+ } else {`
	`240`	`+ $property->setValue($object, $newValue);`
	`241`	`+ }`
`229`	`242`
`230`	`243`	`if ($object instanceof NotifyPropertyChanged) {`
`231`	`244`	`$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'])) {`