FEATURE: Extend DenormalizingObjectConverter to support fromBoolean() and fromInteger()

...in addition to their short version (`fromBool()` and `fromInt()`).
This also adds a short documentation about Value Object property mapping.

Related: #2763

Author: bwaidelich

Neos.Flow/Classes/Property/TypeConverter/DenormalizingObjectConverter.php

@@ -82,10 +82,10 @@ public static function canConvertFromSourceType(string $sourceType, string $targ
                     return method_exists($targetType, 'fromString');
                 case 'bool':
                 case 'boolean':
-                    return method_exists($targetType, 'fromBool');
+                    return method_exists($targetType, 'fromBool') || method_exists($targetType, 'fromBoolean');
                 case 'int':
                 case 'integer':
-                    return method_exists($targetType, 'fromInt');
+                    return method_exists($targetType, 'fromInt') || method_exists($targetType, 'fromInteger');
                 case 'double':
                 case 'float':
                     return method_exists($targetType, 'fromFloat');
@@ -161,9 +161,9 @@ public static function convertFromSource($source, string $targetType)
             case 'string':
                 return $targetType::fromString($source);
             case 'boolean':
-                return $targetType::fromBool($source);
+                return method_exists($targetType, 'fromBool') ? $targetType::fromBool($source) : $targetType::fromBoolean($source);
             case 'integer':
-                return $targetType::fromInt($source);
+                return method_exists($targetType, 'fromInt') ? $targetType::fromInt($source) : $targetType::fromInteger($source);
             case 'double':
                 return $targetType::fromFloat($source);
             default:

Neos.Flow/Documentation/TheDefinitiveGuide/PartIII/PropertyMapping.rst

@@ -354,6 +354,58 @@ body is empty.
   achieve the same without an annotation, by calling ``$this->arguments['comment']->setMapRequestBody(true)`` inside the
   ``initializeCreateAction()`` method.
 
+Mapping Value Objects
+---------------------
+
+Value objects are immutable classes that represent one or more values.
+
+Starting with version 8, Flow can map simple types to the corresponding Value Object if they follow some basic rules:
+
+* They have a *public static* method named ``from<Type>`` that expects exactly one parameter of the given simple type
+  and returns an instance of the class itself
+* They have a private default constructor (this is not required, but encouraged)
+
+Supported simple types and their corresponding named constructor signature:
+
+* ``array`` => ``public static function fromArray(array $array): self``
+* ``boolean`` => ``public static function fromBool(bool $value): self`` (or ``public static function fromBoolean(bool $value): self``
+* ``double``/``float`` => ``public static function fromFloat(double $value): self``
+* ``integer`` => ``public static function fromInt(int $value): self`` (or ``public static function fromInteger(int $value): self``
+* ``string`` => ``public static function fromString(string $value): self``
+
+Example Value Object representing an email address::
+
+	/**
+	 * @Flow\Proxy(false)
+	 */
+	final class EmailAddress
+	{
+	    private function __construct(
+	        public readonly string $value,
+	    ) {
+	        if (filter_var($value, FILTER_VALIDATE_EMAIL) === false) {
+	            throw new \InvalidArgumentException(sprintf('"%s" is not a valid email address', $this->value));
+	        }
+	    }
+
+	    public static function fromString(string $value): self
+	    {
+	        return new self($value);
+	    }
+	}
+
+.. note::
+
+  It's encouraged to add a ``@Flow\Proxy(false)`` annotation to Value Objects because private constructors can't be used
+  and ``new self()`` can't be used otherwise.
+
+With the example above, a corresponding Command- or ActionController can work with the ``EmailAddress` Value Object directly::
+
+	public function someCommand(EmailAddress $email): void
+	{
+	    // $email->value is a valid email address at this point!
+	}
+
 Security Considerations
 -----------------------
 

Neos.Flow/Tests/Unit/Property/TypeConverter/DenormalizingObjectConverterTest.php

@@ -14,9 +14,12 @@
 use Neos\Flow\Property\TypeConverter\DenormalizingObjectConverter;
 use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\ArrayBasedValueObject;
 use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\BooleanBasedValueObject;
+use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\BooleanBasedValueObjectWithLongName;
 use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\FloatBasedValueObject;
 use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\IntegerBasedValueObject;
+use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\IntegerBasedValueObjectWithLongName;
 use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\StringBasedValueObject;
+use Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture\StringBasedValueObjectWithPrivateConstructor;
 use Neos\Flow\Tests\UnitTestCase;
 
 final class DenormalizingObjectConverterTest extends UnitTestCase
@@ -30,7 +33,9 @@ public function identifiesDenormalizableClasses(): void
         $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(ArrayBasedValueObject::class));
         $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(StringBasedValueObject::class));
         $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(BooleanBasedValueObject::class));
+        $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(BooleanBasedValueObjectWithLongName::class));
         $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(IntegerBasedValueObject::class));
+        $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(IntegerBasedValueObjectWithLongName::class));
         $this->assertTrue(DenormalizingObjectConverter::isDenormalizable(FloatBasedValueObject::class));
 
         $this->assertFalse(DenormalizingObjectConverter::isDenormalizable(UnitTestCase::class));
@@ -113,6 +118,35 @@ public function convertsFromBoolean(): void
         $this->assertEquals(true, $resultTrue->getValue());
     }
 
+    /**
+     * @test
+     * @return void
+     */
+    public function canConvertFromBooleanWithLongName(): void
+    {
+        $typeConverter = new DenormalizingObjectConverter();
+        $this->assertTrue($typeConverter->canConvertFrom(true, BooleanBasedValueObjectWithLongName::class));
+    }
+
+    /**
+     * @test
+     * @return void
+     */
+    public function convertsFromBooleanWithLongName(): void
+    {
+        $typeConverter = new DenormalizingObjectConverter();
+        $resultFalse = $typeConverter->convertFrom(false, BooleanBasedValueObjectWithLongName::class);
+
+        $this->assertInstanceOf(BooleanBasedValueObjectWithLongName::class, $resultFalse);
+        $this->assertEquals(false, $resultFalse->getValue());
+
+        $resultTrue = $typeConverter->convertFrom(true, BooleanBasedValueObjectWithLongName::class);
+
+        $this->assertInstanceOf(BooleanBasedValueObjectWithLongName::class, $resultTrue);
+        $this->assertEquals(true, $resultTrue->getValue());
+    }
+
+
     /**
      * @test
      * @return void
@@ -136,6 +170,29 @@ public function convertsFromInteger(): void
         $this->assertEquals(12264, $result->getValue());
     }
 
+    /**
+     * @test
+     * @return void
+     */
+    public function canConvertFromIntegerWithLongName(): void
+    {
+        $typeConverter = new DenormalizingObjectConverter();
+        $this->assertTrue($typeConverter->canConvertFrom(42, IntegerBasedValueObjectWithLongName::class));
+    }
+
+    /**
+     * @test
+     * @return void
+     */
+    public function convertsFromIntegerWithLongName(): void
+    {
+        $typeConverter = new DenormalizingObjectConverter();
+        $result = $typeConverter->convertFrom(12264, IntegerBasedValueObjectWithLongName::class);
+
+        $this->assertInstanceOf(IntegerBasedValueObjectWithLongName::class, $result);
+        $this->assertEquals(12264, $result->getValue());
+    }
+
     /**
      * @test
      * @return void

Neos.Flow/Tests/Unit/Property/TypeConverter/Fixture/BooleanBasedValueObjectWithLongName.php

@@ -0,0 +1,53 @@
+<?php
+namespace Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture;
+
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
+final class BooleanBasedValueObjectWithLongName implements \JsonSerializable
+{
+    /**
+     * @var bool
+     */
+    private $value;
+
+    /**
+     * @param bool $value
+     */
+    private function __construct(bool $value)
+    {
+        $this->value = $value;
+    }
+
+    /**
+     * @param bool $bool
+     * @return self
+     */
+    public static function fromBoolean(bool $bool): self
+    {
+        return new self($bool);
+    }
+
+    /**
+     * @return bool
+     */
+    public function getValue(): bool
+    {
+        return $this->value;
+    }
+
+    /**
+     * @return boolean
+     */
+    public function jsonSerialize()
+    {
+        return $this->value;
+    }
+}

Neos.Flow/Tests/Unit/Property/TypeConverter/Fixture/IntegerBasedValueObjectWithLongName.php

@@ -0,0 +1,53 @@
+<?php
+namespace Neos\Flow\Tests\Unit\Property\TypeConverter\Fixture;
+
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
+final class IntegerBasedValueObjectWithLongName implements \JsonSerializable
+{
+    /**
+     * @var int
+     */
+    private $value;
+
+    /**
+     * @param int $value
+     */
+    private function __construct(int $value)
+    {
+        $this->value = $value;
+    }
+
+    /**
+     * @param int $int
+     * @return self
+     */
+    public static function fromInteger(int $int): self
+    {
+        return new self($int);
+    }
+
+    /**
+     * @return int
+     */
+    public function getValue(): int
+    {
+        return $this->value;
+    }
+
+    /**
+     * @return int
+     */
+    public function jsonSerialize()
+    {
+        return $this->value;
+    }
+}