feature #25493 [Serializer] default_constructor_arguments context option for denormalization (Nek-)

This PR was squashed before being merged into the 4.1-dev branch (closes #25493).

Discussion
----------

[Serializer] `default_constructor_arguments` context option for denormalization

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | (there is no RFC for this)
| License       | MIT
| Doc PR        | symfony/symfony-docs#8914

## Problems

In the case you want to deserialize value-objects, if all the data required by its constructor are **not** given as input, the serializer will throw a simple `RuntimeException` exception. This makes impossible to catch it. (as current fix on my projects I use exception message to be sure to catch the good one X.x")

The second problem is a missing feature to fill the required object with an empty one. This needs to be defined by the user because the serializer can't guess how to build it.

Here is a project that exposes the problem of the current behavior. https://github.com/Nek-/api-platform-value-object

## Solutions suggested

I suggest a solution in 2 parts because the second part is more touchy.

1. Replace the current exception by a new specific one
2. Add a new `empty_data` option to the context of deserialization so you can specify data for objects impossible to instantiate, this is great because the serializer no more throw exception and the validator can then work as expected and send violations to the user. This solution is inspired by forms solutions to fix the issue with value objects

Here is what you can do with this feature:
```php
class DummyValueObject
{
    public function __construct($foo, $bar) { $this->foo = $foo; $this->bar = $bar; }
}

$empty = new DummyValueObject('', '');
$result = $normalizer->denormalize(['foo' => 'Hello'], DummyValueObject::class, 'json', [
    'empty_data' => [
        DummyValueObject::class => $empty,
    ],
]);

// It's impossible to construct a DummyValueObject with only "foo" value. So the serializer
// will replace it with the given empty data
```

There are 2 commits so I can quickly provide you only the first point if you want. Hope you'll like this.

## Solution after discussion

1. New exception `MissingConstructorArgumentsException`
2. New context option `default_constructor_arguments`

```php
class DummyValueObject
{
    public function __construct($foo, $bar) { $this->foo = $foo; $this->bar = $bar; }
}

$result = $normalizer->denormalize(['foo' => 'Hello'], DummyValueObject::class, 'json', [
    'default_constructor_arguments' => [
        DummyValueObject::class => ['foo' => '', 'bar' => ''],
    ],
]);

// DummyValueObject is contructed with the given `foo` and empty `bar`
```

Commits
-------

1523a85542 [Serializer]  context option for denormalization

Author: fabpot

CHANGELOG.md

@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+4.1.0
+-----
+
+* added `MissingConstructorArgumentsException` new exception for deserialization failure
+  of objects that needs data insertion in constructor
+* added an optional `default_constructor_arguments` option of context to specify a default data in
+  case the object is not initializable by its constructor because of data missing
+
 4.0.0
 -----
 

Exception/MissingConstructorArgumentsException.php

@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Exception;
+
+/**
+ * IncompleteInputDataException.
+ *
+ * @author Maxime VEBER <maxime.veber@nekland.fr>
+ */
+class MissingConstructorArgumentsException extends RuntimeException
+{
+}

Normalizer/AbstractNormalizer.php

@@ -12,6 +12,7 @@
 namespace Symfony\Component\Serializer\Normalizer;
 
 use Symfony\Component\Serializer\Exception\CircularReferenceException;
+use Symfony\Component\Serializer\Exception\MissingConstructorArgumentsException;
 use Symfony\Component\Serializer\Exception\InvalidArgumentException;
 use Symfony\Component\Serializer\Exception\LogicException;
 use Symfony\Component\Serializer\Exception\RuntimeException;
@@ -36,6 +37,7 @@ abstract class AbstractNormalizer implements NormalizerInterface, DenormalizerIn
     const GROUPS = 'groups';
     const ATTRIBUTES = 'attributes';
     const ALLOW_EXTRA_ATTRIBUTES = 'allow_extra_attributes';
+    const DEFAULT_CONSTRUCTOR_ARGUMENTS = 'default_constructor_arguments';
 
     /**
      * @var int
@@ -308,6 +310,7 @@ protected function getConstructor(array &$data, $class, array &$context, \Reflec
      * @return object
      *
      * @throws RuntimeException
+     * @throws MissingConstructorArgumentsException
      */
     protected function instantiateObject(array &$data, $class, array &$context, \ReflectionClass $reflectionClass, $allowedAttributes, string $format = null)
     {
@@ -353,10 +356,12 @@ protected function instantiateObject(array &$data, $class, array &$context, \Ref
                     // Don't run set for a parameter passed to the constructor
                     $params[] = $parameterData;
                     unset($data[$key]);
+                } elseif (isset($context[static::DEFAULT_CONSTRUCTOR_ARGUMENTS][$class][$key])) {
+                    $params[] = $context[static::DEFAULT_CONSTRUCTOR_ARGUMENTS][$class][$key];
                 } elseif ($constructorParameter->isDefaultValueAvailable()) {
                     $params[] = $constructorParameter->getDefaultValue();
                 } else {
-                    throw new RuntimeException(
+                    throw new MissingConstructorArgumentsException(
                         sprintf(
                             'Cannot create an instance of %s from serialized data because its constructor requires parameter "%s" to be present.',
                             $class,

Tests/Normalizer/ObjectNormalizerTest.php

@@ -203,6 +203,38 @@ public function testConstructorWithUnknownObjectTypeHintDenormalize()
         $normalizer->denormalize($data, DummyWithConstructorInexistingObject::class);
     }
 
+    /**
+     * @expectedException \Symfony\Component\Serializer\Exception\MissingConstructorArgumentsException
+     * @expectedExceptionMessage Cannot create an instance of Symfony\Component\Serializer\Tests\Normalizer\DummyValueObject from serialized data because its constructor requires parameter "bar" to be present.
+     */
+    public function testConstructorWithMissingData()
+    {
+        $data = array(
+            'foo' => 10,
+        );
+
+        $normalizer = new ObjectNormalizer();
+
+        $normalizer->denormalize($data, DummyValueObject::class);
+    }
+
+    public function testFillWithEmptyDataWhenMissingData()
+    {
+        $data = array(
+            'foo' => 10,
+        );
+
+        $normalizer = new ObjectNormalizer();
+
+        $result = $normalizer->denormalize($data, DummyValueObject::class, 'json', array(
+            'default_constructor_arguments' => array(
+                DummyValueObject::class => array('foo' => '', 'bar' => ''),
+            ),
+        ));
+
+        $this->assertEquals(new DummyValueObject(10, ''), $result);
+    }
+
     public function testGroupsNormalize()
     {
         $classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
@@ -1025,6 +1057,17 @@ public function __construct($id, Unknown $unknown)
     {
     }
 }
+class DummyValueObject
+{
+    private $foo;
+    private $bar;
+
+    public function __construct($foo, $bar)
+    {
+        $this->foo = $foo;
+        $this->bar = $bar;
+    }
+}
 
 class JsonNumber
 {