feat(value): Instantiate immutable DTO value (#FRAM-223)

src/Aggregate/Form.php

@@ -21,6 +21,10 @@
 use Override;
 
 use function assert;
+use function is_array;
+use function is_object;
+use function sprintf;
+use function trigger_error;
 
 /**
  * The base form element
@@ -216,7 +220,7 @@
         }
 
         /** @var T $value */
-        return $this->value = $value;
+        return $this->value = $this->generator->finalize($value);
     }
 
     #[Override]
@@ -296,6 +300,11 @@
     #[Override]
     public function attach($entity): FormInterface
     {
+        /** @psalm-suppress RedundantCondition */
+        if (!is_object($entity) && !is_array($entity)) {
+            @trigger_error(sprintf('Attaching a non-object and non-array value is deprecated since bdf-form 2.0 and will be removed. Got %s.', get_debug_type($entity)), E_USER_DEPRECATED);
+        }
+
         $this->generator->attach($entity);
         $this->value = null; // The value is only attached : it must be filled when calling value()
 

src/Aggregate/FormBuilder.php

@@ -390,7 +390,7 @@ public function generator(ValueGeneratorInterface $generator): FormBuilderInterf
      * {@inheritdoc}
      */
     #[Override]
-    public function generates($entity): FormBuilderInterface
+    public function generates(mixed $entity): FormBuilderInterface
     {
         return $this->generator(new ValueGenerator($entity));
     }

src/Aggregate/FormBuilderInterface.php

@@ -315,7 +315,7 @@ public function generator(ValueGeneratorInterface $generator): FormBuilderInterf
      * });
      * </code>
      *
-     * @param callable|class-string|object|array $entity The entity to generate
+     * @param (callable(ElementInterface):array|object)|class-string|array|object $entity The entity to generate
      *
      * @return $this
      *

src/Aggregate/FormInterface.php

@@ -33,7 +33,7 @@ interface FormInterface extends ChildAggregateInterface
      * $this->repository->save($form->value());
      * </code>
      *
-     * @param T|class-string|callable():T $entity The entity object, or class name
+     * @param T $entity The entity object, or initial array values
      *
      * @return $this
      *

src/Aggregate/Value/ClosureValueGenerator.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Bdf\Form\Aggregate\Value;
+
+use Bdf\Form\ElementInterface;
+use Closure;
+use Override;
+
+/**
+ * Generate a value using a closure
+ *
+ * @template T as array|object
+ * @implements ValueGeneratorInterface<T>
+ */
+final class ClosureValueGenerator implements ValueGeneratorInterface
+{
+    /**
+     * @var T|null
+     */
+    private array|object|null $attachment = null;
+
+    public function __construct(
+        /**
+         * @var Closure(ElementInterface):T
+         */
+        private readonly Closure $generator,
+    ) {}
+
+    #[Override]
+    public function attach(mixed $entity): void
+    {
+        $this->attachment = $entity;
+    }
+
+    #[Override]
+    public function generate(ElementInterface $element): object|array
+    {
+        if ($this->attachment !== null) {
+            return $this->attachment;
+        }
+
+        return ($this->generator)($element);
+    }
+
+    #[Override]
+    public function finalize(object|array $value): object|array
+    {
+        /** @var T */
+        return $value;
+    }
+}

src/Aggregate/Value/ConstructorValueGenerator.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Bdf\Form\Aggregate\Value;
+
+use Bdf\Form\ElementInterface;
+use InvalidArgumentException;
+use Override;
+
+use function assert;
+use function is_array;
+use function sprintf;
+
+/**
+ * Instantiate the form value using its constructor with named parameters
+ * Hydrators will fill an array which will be used as parameters of the class constructor
+ *
+ * @template T as object
+ * @implements ValueGeneratorInterface<T>
+ */
+final class ConstructorValueGenerator implements ValueGeneratorInterface
+{
+    /**
+     * @var T|array|null
+     */
+    private array|object|null $attachment = null;
+
+    public function __construct(
+        /**
+         * @var class-string<T>
+         */
+        private readonly string $class,
+    ) {}
+
+    #[Override]
+    public function attach(mixed $entity): void
+    {
+        if (is_array($entity) || $entity instanceof $this->class) {
+            $this->attachment = $entity;
+            return;
+        }
+
+        throw new InvalidArgumentException(sprintf('Expected array or instance of %s, %s given on %s::attach()', $this->class, get_debug_type($entity), self::class));
+    }
+
+    #[Override]
+    public function generate(ElementInterface $element): object|array
+    {
+        return $this->attachment ?? [];
+    }
+
+    #[Override]
+    public function finalize(object|array $value): object
+    {
+        if (is_array($value)) {
+            $value = new ($this->class)(...$value);
+        }
+
+        assert($value instanceof $this->class);
+
+        return $value;
+    }
+}

src/Aggregate/Value/DefaultConstructorValueGenerator.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Bdf\Form\Aggregate\Value;
+
+use Bdf\Form\ElementInterface;
+use InvalidArgumentException;
+use Override;
+
+use function assert;
+use function get_class;
+use function get_debug_type;
+use function sprintf;
+
+/**
+ * Generate a value by call its constructor without arguments
+ * Properties will be filled directly by hydrators
+ *
+ * @template T as object
+ * @implements ValueGeneratorInterface<T>
+ */
+final class DefaultConstructorValueGenerator implements ValueGeneratorInterface
+{
+    /**
+     * @var T|null
+     */
+    private ?object $attachment = null;
+
+    public function __construct(
+        /**
+         * @var class-string<T>
+         */
+        private readonly string $class,
+    ) {}
+
+    #[Override]
+    public function attach(mixed $entity): void
+    {
+        if (!$entity instanceof $this->class) {
+            throw new InvalidArgumentException(sprintf('Cannot attach a value of type %s, expecting %s', get_debug_type($entity), $this->class));
+        }
+
+        $this->attachment = $entity;
+    }
+
+    #[Override]
+    public function generate(ElementInterface $element): object
+    {
+        if ($this->attachment !== null) {
+            return $this->attachment;
+        }
+
+        return new $this->class;
+    }
+
+    #[Override]
+    public function finalize(object|array $value): object
+    {
+        assert($value instanceof $this->class);
+
+        return $value;
+    }
+}

src/Aggregate/Value/ObjectValueGenerator.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Bdf\Form\Aggregate\Value;
+
+use Bdf\Form\ElementInterface;
+use InvalidArgumentException;
+use Override;
+
+use function assert;
+use function get_class;
+use function get_debug_type;
+use function sprintf;
+
+/**
+ * Generate a value using an object as template which will be cloned for each generation
+ *
+ * @template T as object
+ * @implements ValueGeneratorInterface<T>
+ */
+final class ObjectValueGenerator implements ValueGeneratorInterface
+{
+    /**
+     * @var T|null
+     */
+    private ?object $attachment = null;
+
+    public function __construct(
+        /**
+         * @var T
+         */
+        private readonly object $value,
+    ) {}
+
+    #[Override]
+    public function attach(mixed $entity): void
+    {
+        if (!$entity instanceof $this->value) {
+            throw new InvalidArgumentException(sprintf('Cannot attach a value of type %s, expecting %s', get_debug_type($entity), get_class($this->value)));
+        }
+
+        $this->attachment = $entity;
+    }
+
+    #[Override]
+    public function generate(ElementInterface $element): object
+    {
+        if ($this->attachment !== null) {
+            return $this->attachment;
+        }
+
+        return clone $this->value;
+    }
+
+    #[Override]
+    public function finalize(object|array $value): object
+    {
+        assert($value instanceof $this->value);
+
+        /** @var T */
+        return $value;
+    }
+}

src/Aggregate/Value/SimpleValueGenerator.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Bdf\Form\Aggregate\Value;
+
+use Bdf\Form\ElementInterface;
+use Override;
+
+/**
+ * Simply return the stored value
+ *
+ * @template T as array|object
+ * @implements ValueGeneratorInterface<T>
+ */
+final class SimpleValueGenerator implements ValueGeneratorInterface
+{
+    public function __construct(
+        /**
+         * @var T
+         */
+        private array|object $value = [],
+    ) {}
+
+    #[Override]
+    public function attach(mixed $entity): void
+    {
+        $this->value = $entity;
+    }
+
+    #[Override]
+    public function generate(ElementInterface $element): object|array
+    {
+        return $this->value;
+    }
+
+    #[Override]
+    public function finalize(object|array $value): object|array
+    {
+        /** @var T */
+        return $value;
+    }
+}