feature #19197 [Serializer][FrameworkBundle] Add a CSV encoder (dunglas)

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

Discussion
----------

[Serializer][FrameworkBundle] Add a CSV encoder

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

Usage:

```php
use Symfony\Component\Serializer\Serializer;
use Symfony\Component\Serializer\Encoder\CsvEncoder;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

$serializer = new Serializer(array(new ObjectNormalizer()), array(new CsvEncoder()));
// or $serializer = $container->get('serializer'); when using the full stack framework
$serializer->encode($something, 'csv');
$serializer->decode(<<<'CSV'
id,name
1,Kévin
CSV
, 'csv');
```

CSV files must contain a header line with property names as keys.

ping @clementtalleu @Simperfit @gorghoa

Commits
-------

e71f5be [Serializer][FrameworkBundle] Add a CSV encoder

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

@@ -27,6 +27,7 @@ use Symfony\Component\HttpKernel\DependencyInjection\Extension;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\PropertyAccess\PropertyAccessor;
 use Symfony\Component\Serializer\Encoder\YamlEncoder;
+use Symfony\Component\Serializer\Encoder\CsvEncoder;
 use Symfony\Component\Serializer\Mapping\Factory\CacheClassMetadataFactory;
 use Symfony\Component\Serializer\Normalizer\DataUriNormalizer;
 use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
@@ -1045,6 +1046,12 @@ class FrameworkExtension extends Extension
             $definition->addTag('serializer.encoder');
         }
 
+        if (class_exists(CsvEncoder::class)) {
+            $definition = $container->register('serializer.encoder.csv', CsvEncoder::class);
+            $definition->setPublic(false);
+            $definition->addTag('serializer.encoder');
+        }
+
         $loader->load('serializer.xml');
         $chainLoader = $container->getDefinition('serializer.mapping.chain_loader');
 

src/Symfony/Component/Serializer/Encoder/CsvEncoder.php

@@ -0,0 +1,181 @@
+<?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\Encoder;
+
+use Symfony\Component\Serializer\Exception\InvalidArgumentException;
+
+/**
+ * Encodes CSV data.
+ *
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class CsvEncoder implements EncoderInterface, DecoderInterface
+{
+    const FORMAT = 'csv';
+
+    private $delimiter;
+    private $enclosure;
+    private $escapeChar;
+    private $keySeparator;
+
+    /**
+     * @param string $delimiter
+     * @param string $enclosure
+     * @param string $escapeChar
+     * @param string $keySeparator
+     */
+    public function __construct($delimiter = ',', $enclosure = '"', $escapeChar = '\\', $keySeparator = '.')
+    {
+        $this->delimiter = $delimiter;
+        $this->enclosure = $enclosure;
+        $this->escapeChar = $escapeChar;
+        $this->keySeparator = $keySeparator;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function encode($data, $format, array $context = array())
+    {
+        $handle = fopen('php://temp,', 'w+');
+
+        if (!is_array($data)) {
+            $data = array(array($data));
+        } elseif (empty($data)) {
+            $data = array(array());
+        } else {
+            // Sequential arrays of arrays are considered as collections
+            $i = 0;
+            foreach ($data as $key => $value) {
+                if ($i !== $key || !is_array($value)) {
+                    $data = array($data);
+                    break;
+                }
+
+                ++$i;
+            }
+        }
+
+        $headers = null;
+        foreach ($data as $value) {
+            $result = array();
+            $this->flatten($value, $result);
+
+            if (null === $headers) {
+                $headers = array_keys($result);
+                fputcsv($handle, $headers, $this->delimiter, $this->enclosure, $this->escapeChar);
+            } elseif (array_keys($result) !== $headers) {
+                throw new InvalidArgumentException('To use the CSV encoder, each line in the data array must have the same structure. You may want to use a custom normalizer class to normalize the data format before passing it to the CSV encoder.');
+            }
+
+            fputcsv($handle, $result, $this->delimiter, $this->enclosure, $this->escapeChar);
+        }
+
+        rewind($handle);
+        $value = stream_get_contents($handle);
+        fclose($handle);
+
+        return $value;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsEncoding($format)
+    {
+        return self::FORMAT === $format;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function decode($data, $format, array $context = array())
+    {
+        $handle = fopen('php://temp', 'r+');
+        fwrite($handle, $data);
+        rewind($handle);
+
+        $headers = null;
+        $nbHeaders = 0;
+        $result = array();
+
+        while (false !== ($cols = fgetcsv($handle, 0, $this->delimiter, $this->enclosure, $this->escapeChar))) {
+            $nbCols = count($cols);
+
+            if (null === $headers) {
+                $nbHeaders = $nbCols;
+
+                foreach ($cols as $col) {
+                    $headers[] = explode($this->keySeparator, $col);
+                }
+
+                continue;
+            }
+
+            $item = array();
+            for ($i = 0; ($i < $nbCols) && ($i < $nbHeaders); ++$i) {
+                $depth = count($headers[$i]);
+                $arr = &$item;
+                for ($j = 0; $j < $depth; ++$j) {
+                    // Handle nested arrays
+                    if ($j === ($depth - 1)) {
+                        $arr[$headers[$i][$j]] = $cols[$i];
+
+                        continue;
+                    }
+
+                    if (!isset($arr[$headers[$i][$j]])) {
+                        $arr[$headers[$i][$j]] = array();
+                    }
+
+                    $arr = &$arr[$headers[$i][$j]];
+                }
+            }
+
+            $result[] = $item;
+        }
+        fclose($handle);
+
+        if (empty($result) || isset($result[1])) {
+            return $result;
+        }
+
+        // If there is only one data line in the document, return it (the line), the result is not considered as a collection
+        return $result[0];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsDecoding($format)
+    {
+        return self::FORMAT === $format;
+    }
+
+    /**
+     * Flattens an array and generates keys including the path.
+     *
+     * @param array  $array
+     * @param array  $result
+     * @param string $parentKey
+     */
+    private function flatten(array $array, array &$result, $parentKey = '')
+    {
+        foreach ($array as $key => $value) {
+            if (is_array($value)) {
+                $this->flatten($value, $result, $parentKey.$key.$this->keySeparator);
+            } else {
+                $result[$parentKey.$key] = $value;
+            }
+        }
+    }
+}

src/Symfony/Component/Serializer/Tests/Encoder/CsvEncoderTest.php

@@ -0,0 +1,231 @@
+<?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\Encoder;
+
+use Symfony\Component\Serializer\Encoder\CsvEncoder;
+
+/**
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class CsvEncoderTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var CsvEncoder
+     */
+    private $encoder;
+
+    protected function setUp()
+    {
+        $this->encoder = new CsvEncoder();
+    }
+
+    public function testSupportEncoding()
+    {
+        $this->assertTrue($this->encoder->supportsEncoding('csv'));
+        $this->assertFalse($this->encoder->supportsEncoding('foo'));
+    }
+
+    public function testEncode()
+    {
+        $value = array('foo' => 'hello', 'bar' => 'hey ho');
+
+        $this->assertEquals(<<<'CSV'
+foo,bar
+hello,"hey ho"
+
+CSV
+    , $this->encoder->encode($value, 'csv'));
+    }
+
+    public function testEncodeCollection()
+    {
+        $value = array(
+            array('foo' => 'hello', 'bar' => 'hey ho'),
+            array('foo' => 'hi', 'bar' => 'let\'s go'),
+        );
+
+        $this->assertEquals(<<<'CSV'
+foo,bar
+hello,"hey ho"
+hi,"let's go"
+
+CSV
+    , $this->encoder->encode($value, 'csv'));
+    }
+
+    public function testEncodePlainIndexedArray()
+    {
+        $this->assertEquals(<<<'CSV'
+0,1,2
+a,b,c
+
+CSV
+            , $this->encoder->encode(array('a', 'b', 'c'), 'csv'));
+    }
+
+    public function testEncodeNonArray()
+    {
+        $this->assertEquals(<<<'CSV'
+0
+foo
+
+CSV
+            , $this->encoder->encode('foo', 'csv'));
+    }
+
+    public function testEncodeNestedArrays()
+    {
+        $value = array('foo' => 'hello', 'bar' => array(
+            array('id' => 'yo', 1 => 'wesh'),
+            array('baz' => 'Halo', 'foo' => 'olá'),
+        ));
+
+        $this->assertEquals(<<<'CSV'
+foo,bar.0.id,bar.0.1,bar.1.baz,bar.1.foo
+hello,yo,wesh,Halo,olá
+
+CSV
+    , $this->encoder->encode($value, 'csv'));
+    }
+
+    public function testEncodeCustomSettings()
+    {
+        $this->encoder = new CsvEncoder(';', "'", '|', '-');
+
+        $value = array('a' => 'he\'llo', 'c' => array('d' => 'foo'));
+
+        $this->assertEquals(<<<'CSV'
+a;c-d
+'he''llo';foo
+
+CSV
+    , $this->encoder->encode($value, 'csv'));
+    }
+
+    public function testEncodeEmptyArray()
+    {
+        $this->assertEquals("\n\n", $this->encoder->encode(array(), 'csv'));
+        $this->assertEquals("\n\n", $this->encoder->encode(array(array()), 'csv'));
+    }
+
+    /**
+     * @expectedException \Symfony\Component\Serializer\Exception\InvalidArgumentException
+     */
+    public function testEncodeNonFlattenableStructure()
+    {
+        $this->encoder->encode(array(array('a' => array('foo', 'bar')), array('a' => array())), 'csv');
+    }
+
+    public function testSupportsDecoding()
+    {
+        $this->assertTrue($this->encoder->supportsDecoding('csv'));
+        $this->assertFalse($this->encoder->supportsDecoding('foo'));
+    }
+
+    public function testDecode()
+    {
+        $expected = array('foo' => 'a', 'bar' => 'b');
+
+        $this->assertEquals($expected, $this->encoder->decode(<<<'CSV'
+foo,bar
+a,b
+CSV
+        , 'csv'));
+    }
+
+    public function testDecodeCollection()
+    {
+        $expected = array(
+            array('foo' => 'a', 'bar' => 'b'),
+            array('foo' => 'c', 'bar' => 'd'),
+            array('foo' => 'f'),
+        );
+
+        $this->assertEquals($expected, $this->encoder->decode(<<<'CSV'
+foo,bar
+a,b
+c,d
+f
+
+CSV
+        , 'csv'));
+    }
+
+    public function testDecodeToManyRelation()
+    {
+        $expected = array(
+            array('foo' => 'bar', 'relations' => array(array('a' => 'b'), array('a' => 'b'))),
+            array('foo' => 'bat', 'relations' => array(array('a' => 'b'), array('a' => ''))),
+            array('foo' => 'bat', 'relations' => array(array('a' => 'b'))),
+            array('foo' => 'baz', 'relations' => array(array('a' => 'c'), array('a' => 'c'))),
+        );
+
+        $this->assertEquals($expected, $this->encoder->decode(<<<'CSV'
+foo,relations.0.a,relations.1.a
+bar,b,b
+bat,b,
+bat,b
+baz,c,c
+CSV
+            , 'csv'));
+    }
+
+    public function testDecodeNestedArrays()
+    {
+        $expected = array(
+            array('foo' => 'a', 'bar' => array('baz' => array('bat' => 'b'))),
+            array('foo' => 'c', 'bar' => array('baz' => array('bat' => 'd'))),
+        );
+
+        $this->assertEquals($expected, $this->encoder->decode(<<<'CSV'
+foo,bar.baz.bat
+a,b
+c,d
+CSV
+        , 'csv'));
+    }
+
+    public function testDecodeCustomSettings()
+    {
+        $this->encoder = new CsvEncoder(';', "'", '|', '-');
+
+        $expected = array('a' => 'hell\'o', 'bar' => array('baz' => 'b'));
+        $this->assertEquals($expected, $this->encoder->decode(<<<'CSV'
+a;bar-baz
+'hell''o';b;c
+CSV
+        , 'csv'));
+    }
+
+    public function testDecodeMalformedCollection()
+    {
+        $expected = array(
+            array('foo' => 'a', 'bar' => 'b'),
+            array('foo' => 'c', 'bar' => 'd'),
+            array('foo' => 'f'),
+        );
+
+        $this->assertEquals($expected, $this->encoder->decode(<<<'CSV'
+foo,bar
+a,b,e
+c,d,g,h
+f
+
+CSV
+            , 'csv'));
+    }
+
+    public function testDecodeEmptyArray()
+    {
+        $this->assertEquals(array(), $this->encoder->decode('', 'csv'));
+    }
+}