feature #24375 [Serializer] Serialize and deserialize from abstract classes (sroze)

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

Discussion
----------

[Serializer] Serialize and deserialize from abstract classes

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | ø
| License       | MIT
| Doc PR        | Not yet

This PR adds a feature in the Serializer: allow to serialize and de-serialize abstract classes. Such feature is especially useful when dealing with domain objects.

# Example

Let's take the example of the following objects:
- `CodeRepository` defines a set of properties like `name` and `url`
- `GitHubCodeRepository` and `BitBucketCodeRepository` extends from the abstract `CodeRepository` class and adds a few properties.
- `Project` has a relation with a `codeRepository`, which has a type `CodeRepository`.

At the moment, the serializer can't serialize/deserialize correctly this `Project` object has it doesn't know how to deal with this `CodeRepository` abstract object.

This feature allows the serializer to deal with such situation. The `ObjectNormalizer` has now access to a `ClassDiscriminatorResolver` that knows, for a given abstract class:
- Is the "type" property it needs to read/write to uniquely identify each sub-class
- What's the name of the "type" for each sub-class mapping

# Usage without Framework Bundle

```php
$discriminatorResolver = new ClassDiscriminatorResolver();
$discriminatorResolver->addClassMapping(CodeRepository::class, new ClassDiscriminatorMapping('type', [
    'github' => GitHubCodeRepository::class,
    'bitbucket' => BitBucketCodeRepository::class,
]));

$serializer = new Serializer(array(new ObjectNormalizer(null, null, null, null, $discriminatorResolver)), array('json' => new JsonEncoder()));

$serialized = $serializer->serialize(new GitHubCodeRepository());
// {"type": "github"}

$repository = $serializer->unserialize($serialized, CodeRepository::class, 'json');
// GitHubCodeRepository

```

# Usage with the Framework Bundle

```yaml
framework:
    serializer:
        discriminator_class_mapping:
            App\CodeRepository:
                 type_property: type
                 mapping:
                    github: App\GitHubCodeRepository
                    bitbucket: App\BitBucketCodeRepository
```

# Usage with Annotations/XML/YAML

```php
use Symfony\Component\Serializer\Annotation\DiscriminatorMap;

/**
 * @DiscriminatorMap(typeProperty="type", mapping={
 *    "first"="Symfony\Component\Serializer\Tests\Fixtures\AbstractDummyFirstChild",
 *    "second"="Symfony\Component\Serializer\Tests\Fixtures\AbstractDummySecondChild"
 * })
 */
abstract class AbstractDummy
{
    public $foo;

    public function __construct($foo = null)
    {
        $this->foo = $foo;
    }
}
```

# TODO

- [x] Working as standalone
- [x] Working with the framework bundle
- [x] Tests on mapping classes

Commits
-------

4c6e05b7ee [Serializer] Serialize and deserialize from abstract classes

Author: fabpot

Annotation/DiscriminatorMap.php

@@ -0,0 +1,64 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Annotation;
+
+use Symfony\Component\Serializer\Exception\InvalidArgumentException;
+
+/**
+ * Annotation class for @DiscriminatorMap().
+ *
+ * @Annotation
+ * @Target({"CLASS"})
+ *
+ * @author Samuel Roze <[email protected]>
+ */
+class DiscriminatorMap
+{
+    /**
+     * @var string
+     */
+    private $typeProperty;
+
+    /**
+     * @var array
+     */
+    private $mapping;
+
+    /**
+     * @param array $data
+     *
+     * @throws InvalidArgumentException
+     */
+    public function __construct(array $data)
+    {
+        if (empty($data['typeProperty'])) {
+            throw new InvalidArgumentException(sprintf('Parameter "typeProperty" of annotation "%s" cannot be empty.', get_class($this)));
+        }
+
+        if (empty($data['mapping'])) {
+            throw new InvalidArgumentException(sprintf('Parameter "mapping" of annotation "%s" cannot be empty.', get_class($this)));
+        }
+
+        $this->typeProperty = $data['typeProperty'];
+        $this->mapping = $data['mapping'];
+    }
+
+    public function getTypeProperty(): string
+    {
+        return $this->typeProperty;
+    }
+
+    public function getMapping(): array
+    {
+        return $this->mapping;
+    }
+}

Mapping/ClassDiscriminatorFromClassMetadata.php

@@ -0,0 +1,92 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Mapping;
+
+use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactoryInterface;
+
+/**
+ * @author Samuel Roze <[email protected]>
+ */
+class ClassDiscriminatorFromClassMetadata implements ClassDiscriminatorResolverInterface
+{
+    /**
+     * @var ClassMetadataFactoryInterface
+     */
+    private $classMetadataFactory;
+    private $mappingForMappedObjectCache = array();
+
+    public function __construct(ClassMetadataFactoryInterface $classMetadataFactory)
+    {
+        $this->classMetadataFactory = $classMetadataFactory;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getMappingForClass(string $class): ?ClassDiscriminatorMapping
+    {
+        if ($this->classMetadataFactory->hasMetadataFor($class)) {
+            return $this->classMetadataFactory->getMetadataFor($class)->getClassDiscriminatorMapping();
+        }
+
+        return null;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getMappingForMappedObject($object): ?ClassDiscriminatorMapping
+    {
+        if ($this->classMetadataFactory->hasMetadataFor($object)) {
+            $metadata = $this->classMetadataFactory->getMetadataFor($object);
+
+            if (null !== $metadata->getClassDiscriminatorMapping()) {
+                return $metadata->getClassDiscriminatorMapping();
+            }
+        }
+
+        $cacheKey = is_object($object) ? get_class($object) : $object;
+        if (!array_key_exists($cacheKey, $this->mappingForMappedObjectCache)) {
+            $this->mappingForMappedObjectCache[$cacheKey] = $this->resolveMappingForMappedObject($object);
+        }
+
+        return $this->mappingForMappedObjectCache[$cacheKey];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getTypeForMappedObject($object): ?string
+    {
+        if (null === $mapping = $this->getMappingForMappedObject($object)) {
+            return null;
+        }
+
+        return $mapping->getMappedObjectType($object);
+    }
+
+    private function resolveMappingForMappedObject($object)
+    {
+        $reflectionClass = new \ReflectionClass($object);
+        if ($parentClass = $reflectionClass->getParentClass()) {
+            return $this->getMappingForMappedObject($parentClass->getName());
+        }
+
+        foreach ($reflectionClass->getInterfaceNames() as $interfaceName) {
+            if (null !== ($interfaceMapping = $this->getMappingForMappedObject($interfaceName))) {
+                return $interfaceMapping;
+            }
+        }
+
+        return null;
+    }
+}

Mapping/ClassDiscriminatorMapping.php

@@ -0,0 +1,62 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Mapping;
+
+/**
+ * @author Samuel Roze <[email protected]>
+ */
+class ClassDiscriminatorMapping
+{
+    private $typeProperty;
+    private $typesMapping;
+
+    public function __construct(string $typeProperty, array $typesMapping = array())
+    {
+        $this->typeProperty = $typeProperty;
+        $this->typesMapping = $typesMapping;
+    }
+
+    public function getTypeProperty(): string
+    {
+        return $this->typeProperty;
+    }
+
+    public function getClassForType(string $type): ?string
+    {
+        if (isset($this->typesMapping[$type])) {
+            return $this->typesMapping[$type];
+        }
+
+        return null;
+    }
+
+    /**
+     * @param object|string $object
+     *
+     * @return string|null
+     */
+    public function getMappedObjectType($object): ?string
+    {
+        foreach ($this->typesMapping as $type => $typeClass) {
+            if (is_a($object, $typeClass)) {
+                return $type;
+            }
+        }
+
+        return null;
+    }
+
+    public function getTypesMapping(): array
+    {
+        return $this->typesMapping;
+    }
+}

Mapping/ClassDiscriminatorResolverInterface.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Mapping;
+
+/**
+ * Knows how to get the class discriminator mapping for classes and objects.
+ *
+ * @author Samuel Roze <[email protected]>
+ */
+interface ClassDiscriminatorResolverInterface
+{
+    /**
+     * @param string $class
+     *
+     * @return ClassDiscriminatorMapping|null
+     */
+    public function getMappingForClass(string $class): ?ClassDiscriminatorMapping;
+
+    /**
+     * @param object|string $object
+     *
+     * @return ClassDiscriminatorMapping|null
+     */
+    public function getMappingForMappedObject($object): ?ClassDiscriminatorMapping;
+
+    /**
+     * @param object|string $object
+     *
+     * @return string|null
+     */
+    public function getTypeForMappedObject($object): ?string;
+}

Mapping/ClassMetadata.php

@@ -39,9 +39,25 @@ class ClassMetadata implements ClassMetadataInterface
      */
     private $reflClass;
 
-    public function __construct(string $class)
+    /**
+     * @var ClassDiscriminatorMapping|null
+     *
+     * @internal This property is public in order to reduce the size of the
+     *           class' serialized representation. Do not access it. Use
+     *           {@link getClassDiscriminatorMapping()} instead.
+     */
+    public $classDiscriminatorMapping;
+
+    /**
+     * Constructs a metadata for the given class.
+     *
+     * @param string                         $class
+     * @param ClassDiscriminatorMapping|null $classDiscriminatorMapping
+     */
+    public function __construct(string $class, ClassDiscriminatorMapping $classDiscriminatorMapping = null)
     {
         $this->name = $class;
+        $this->classDiscriminatorMapping = $classDiscriminatorMapping;
     }
 
     /**
@@ -94,6 +110,22 @@ public function getReflectionClass()
         return $this->reflClass;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getClassDiscriminatorMapping()
+    {
+        return $this->classDiscriminatorMapping;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setClassDiscriminatorMapping(ClassDiscriminatorMapping $mapping = null)
+    {
+        $this->classDiscriminatorMapping = $mapping;
+    }
+
     /**
      * Returns the names of the properties that should be serialized.
      *
@@ -104,6 +136,7 @@ public function __sleep()
         return array(
             'name',
             'attributesMetadata',
+            'classDiscriminatorMapping',
         );
     }
 }

Mapping/ClassMetadataInterface.php

@@ -54,4 +54,14 @@ public function merge(ClassMetadataInterface $classMetadata);
      * @return \ReflectionClass
      */
     public function getReflectionClass();
+
+    /**
+     * @return ClassDiscriminatorMapping|null
+     */
+    public function getClassDiscriminatorMapping();
+
+    /**
+     * @param ClassDiscriminatorMapping|null $mapping
+     */
+    public function setClassDiscriminatorMapping(ClassDiscriminatorMapping $mapping = null);
 }

Mapping/Loader/AnnotationLoader.php

@@ -12,10 +12,12 @@
 namespace Symfony\Component\Serializer\Mapping\Loader;
 
 use Doctrine\Common\Annotations\Reader;
+use Symfony\Component\Serializer\Annotation\DiscriminatorMap;
 use Symfony\Component\Serializer\Annotation\Groups;
 use Symfony\Component\Serializer\Annotation\MaxDepth;
 use Symfony\Component\Serializer\Exception\MappingException;
 use Symfony\Component\Serializer\Mapping\AttributeMetadata;
+use Symfony\Component\Serializer\Mapping\ClassDiscriminatorMapping;
 use Symfony\Component\Serializer\Mapping\ClassMetadataInterface;
 
 /**
@@ -43,6 +45,15 @@ public function loadClassMetadata(ClassMetadataInterface $classMetadata)
 
         $attributesMetadata = $classMetadata->getAttributesMetadata();
 
+        foreach ($this->reader->getClassAnnotations($reflectionClass) as $annotation) {
+            if ($annotation instanceof DiscriminatorMap) {
+                $classMetadata->setClassDiscriminatorMapping(new ClassDiscriminatorMapping(
+                    $annotation->getTypeProperty(),
+                    $annotation->getMapping()
+                ));
+            }
+        }
+
         foreach ($reflectionClass->getProperties() as $property) {
             if (!isset($attributesMetadata[$property->name])) {
                 $attributesMetadata[$property->name] = new AttributeMetadata($property->name);

Mapping/Loader/XmlFileLoader.php

@@ -14,6 +14,7 @@
 use Symfony\Component\Config\Util\XmlUtils;
 use Symfony\Component\Serializer\Exception\MappingException;
 use Symfony\Component\Serializer\Mapping\AttributeMetadata;
+use Symfony\Component\Serializer\Mapping\ClassDiscriminatorMapping;
 use Symfony\Component\Serializer\Mapping\ClassMetadataInterface;
 
 /**
@@ -67,6 +68,18 @@ public function loadClassMetadata(ClassMetadataInterface $classMetadata)
                 }
             }
 
+            if (isset($xml->{'discriminator-map'})) {
+                $mapping = array();
+                foreach ($xml->{'discriminator-map'}->mapping as $element) {
+                    $mapping[(string) $element->attributes()->type] = (string) $element->attributes()->class;
+                }
+
+                $classMetadata->setClassDiscriminatorMapping(new ClassDiscriminatorMapping(
+                    (string) $xml->{'discriminator-map'}->attributes()->{'type-property'},
+                    $mapping
+                ));
+            }
+
             return true;
         }