feature #17411 [Serializer] Add a new DateTime normalizer (dunglas)

This PR was merged into the 3.1-dev branch.

Discussion
----------

[Serializer] Add a new DateTime normalizer

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | todo

This PR add support for dates and times to the Normalizer component. It supports all date and time formats supported by PHP. Dates and times are normalized in the RFC 3339 format by default. The output format can be customized using the `$context` parameter. The default format can be changed using a constructor parameter.

Usage:

```php
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
use Symfony\Component\Serializer\Serializer;

$serializer = new Serializer(array(new DateTimeNormalizer()));

echo $serializer->normalize(new \DateTimeImmutable('2016/01/01'));
// 2016-01-01T00:00:00+00:00

echo $serializer->normalize(new \DateTime('2016/01/01'));
// 2016-01-01T00:00:00+00:00

echo $serializer->normalize(new \DateTime('2016/01/01'), null, array(DateTimeNormalizer::FORMAT_KEY => 'Y'))
// 2016

var_dump($serializer->denormalize('2016-01-01T00:00:00+00:00', \DateTimeInterface::class));
// class DateTimeImmutable#1 (3) {
//   public $date =>
//   string(26) "2016-01-01 00:00:00.000000"
//   public $timezone_type =>
//   int(1)
//   public $timezone =>
//   string(6) "+00:00"
// }

var_dump($serializer->denormalize('2016-01-01T00:00:00+00:00', \DateTime::class));
// class DateTime#1 (3) {
//   public $date =>
//   string(26) "2016-01-01 00:00:00.000000"
//   public $timezone_type =>
//   int(1)
//   public $timezone =>
//   string(6) "+00:00"
// }
```

Commits
-------

6749a70 [Serializer] Add a new DateTime normalizer

src/Symfony/Component/Serializer/Normalizer/DateTimeNormalizer.php

@@ -0,0 +1,91 @@
+<?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\Normalizer;
+
+use Symfony\Component\Serializer\Exception\InvalidArgumentException;
+use Symfony\Component\Serializer\Exception\UnexpectedValueException;
+
+/**
+ * Normalizes an object implementing the {@see \DateTimeInterface} to a date string.
+ * Denormalizes a date string to an instance of {@see \DateTime} or {@see \DateTimeImmutable}.
+ *
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class DateTimeNormalizer implements NormalizerInterface, DenormalizerInterface
+{
+    const FORMAT_KEY = 'datetime_format';
+
+    /**
+     * @var string
+     */
+    private $format;
+
+    /**
+     * @param string $format
+     */
+    public function __construct($format = \DateTime::RFC3339)
+    {
+        $this->format = $format;
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @throws InvalidArgumentException
+     */
+    public function normalize($object, $format = null, array $context = array())
+    {
+        if (!$object instanceof \DateTimeInterface) {
+            throw new InvalidArgumentException('The object must implement the "\DateTimeInterface".');
+        }
+
+        $format = isset($context[self::FORMAT_KEY]) ? $context[self::FORMAT_KEY] : $this->format;
+
+        return $object->format($format);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsNormalization($data, $format = null)
+    {
+        return $data instanceof \DateTimeInterface;
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @throws UnexpectedValueException
+     */
+    public function denormalize($data, $class, $format = null, array $context = array())
+    {
+        try {
+            return \DateTime::class === $class ? new \DateTime($data) : new \DateTimeImmutable($data);
+        } catch (\Exception $e) {
+            throw new UnexpectedValueException($e->getMessage(), $e->getCode(), $e);
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsDenormalization($data, $type, $format = null)
+    {
+        $supportedTypes = array(
+            \DateTimeInterface::class => true,
+            \DateTimeImmutable::class => true,
+            \DateTime::class => true,
+        );
+
+        return isset($supportedTypes[$type]);
+    }
+}

src/Symfony/Component/Serializer/Tests/Normalizer/DateTimeNormalizerTest.php

@@ -0,0 +1,85 @@
+<?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\Tests\Normalizer;
+
+use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
+
+/**
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class DateTimeNormalizerTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var DateTimeNormalizer
+     */
+    private $normalizer;
+
+    public function setUp()
+    {
+        $this->normalizer = new DateTimeNormalizer();
+    }
+
+    public function testSupportNormalization()
+    {
+        $this->assertTrue($this->normalizer->supportsNormalization(new \DateTime()));
+        $this->assertTrue($this->normalizer->supportsNormalization(new \DateTimeImmutable()));
+        $this->assertFalse($this->normalizer->supportsNormalization(new \stdClass()));
+    }
+
+    public function testNormalize()
+    {
+        $this->assertEquals('2016-01-01T00:00:00+00:00', $this->normalizer->normalize(new \DateTime('2016/01/01')));
+        $this->assertEquals('2016-01-01T00:00:00+00:00', $this->normalizer->normalize(new \DateTimeImmutable('2016/01/01')));
+    }
+
+    public function testContextFormat()
+    {
+        $this->assertEquals('2016', $this->normalizer->normalize(new \DateTime('2016/01/01'), null, array(DateTimeNormalizer::FORMAT_KEY => 'Y')));
+    }
+
+    public function testConstructorFormat()
+    {
+        $this->assertEquals('16', (new DateTimeNormalizer('y'))->normalize(new \DateTime('2016/01/01')));
+    }
+
+    /**
+     * @expectedException \Symfony\Component\Serializer\Exception\InvalidArgumentException
+     * @expectedExceptionMessage The object must implement the "\DateTimeInterface".
+     */
+    public function testInvalidDataThrowException()
+    {
+        $this->normalizer->normalize(new \stdClass());
+    }
+
+    public function testSupportDenormalization()
+    {
+        $this->assertTrue($this->normalizer->supportsDenormalization('2016-01-01T00:00:00+00:00', \DateTimeInterface::class));
+        $this->assertTrue($this->normalizer->supportsDenormalization('2016-01-01T00:00:00+00:00', \DateTime::class));
+        $this->assertTrue($this->normalizer->supportsDenormalization('2016-01-01T00:00:00+00:00', \DateTimeImmutable::class));
+        $this->assertFalse($this->normalizer->supportsDenormalization('foo', 'Bar'));
+    }
+
+    public function testDenormalize()
+    {
+        $this->assertEquals(new \DateTimeImmutable('2016/01/01'), $this->normalizer->denormalize('2016-01-01T00:00:00+00:00', \DateTimeInterface::class));
+        $this->assertEquals(new \DateTimeImmutable('2016/01/01'), $this->normalizer->denormalize('2016-01-01T00:00:00+00:00', \DateTimeImmutable::class));
+        $this->assertEquals(new \DateTime('2016/01/01'), $this->normalizer->denormalize('2016-01-01T00:00:00+00:00', \DateTime::class));
+    }
+
+    /**
+     * @expectedException \Symfony\Component\Serializer\Exception\UnexpectedValueException
+     */
+    public function testInvalidDateThrowException()
+    {
+        $this->normalizer->denormalize('invalid date', \DateTimeInterface::class);
+    }
+}