feat: Add CSV support to DataMapper and update documentation

Author: awu

README.md

@@ -18,7 +18,7 @@
 
 A Symfony integration for [wundii/data-mapper](https://github.com/wundii/data-mapper). 
 This library is an extremely fast and strictly typed object mapper built for modern PHP (8.2+). 
-It seamlessly transforms data from formats like JSON, NEON, XML, YAML, arrays, and standard objects into well-structured PHP objects.
+It seamlessly transforms data from formats like CSV, JSON, NEON, XML, YAML, array, and standard objects into well-structured PHP objects.
 
 Ideal for developers who need reliable and efficient data mapping without sacrificing code quality or modern best practices.
 
@@ -49,6 +49,7 @@ Ideal for developers who need reliable and efficient data mapping without sacrif
 ## Supported Formats
 optional formats are marked with an asterisk `*`
 - `array`
+- `csv`
 - `json`
 - `neon`*
 - `object`

composer.json

@@ -1,8 +1,8 @@
 {
   "name": "wundii/data-mapper-symfony-bundle",
   "type": "symfony-bundle",
-  "description": "A Symfony integration for wundii/data-mapper, modern and fast object mapper for PHP 8.2+. Strict types. Converts JSON, XML, YAML, NEON, arrays, and objects to PHP objects.",
-  "keywords": ["symfony","symfony-bundle","bundle","datamapper","mapper","xml","json","array","object", "deserialization", "deserialize"],
+  "description": "A Symfony integration for wundii/data-mapper, modern and fast object mapper for PHP 8.2+. Strict types. Converts CSV, JSON, XML, YAML, NEON, arrays, and objects to PHP objects.",
+  "keywords": ["symfony","symfony-bundle","bundle","datamapper","mapper","xml","json","csv","array","object", "deserialization", "deserialize"],
   "license": "MIT",
   "authors": [
     {
@@ -64,33 +64,15 @@
       "@ecs-dry",
       "@unittest"
     ],
-    "rector-dry": [
-      "php vendor/bin/rector process --dry-run --ansi"
-    ],
-    "rector-apply": [
-      "php vendor/bin/rector process --ansi"
-    ],
-    "ecs-dry": [
-      "php vendor/bin/ecs check"
-    ],
-    "ecs-apply": [
-      "php vendor/bin/ecs check --fix"
-    ],
-    "phpstan": [
-      "php vendor/bin/phpstan analyse"
-    ],
-    "unittest": [
-      "php vendor/bin/phpunit --configuration phpunit.xml"
-    ],
-    "cache-clear": [
-      "rm -R ./Cache/* -f"
-    ],
-    "phplint": [
-      "php vendor/bin/phplint"
-    ],
-    "coverage": [
-      "php vendor/bin/phpunit --coverage-clover coverage.xml"
-    ]
+    "cache-clear": "rm -R ./cache/* -f",
+    "coverage": "php vendor/bin/phpunit --coverage-clover coverage.xml",
+    "ecs-apply": "php vendor/bin/ecs check --fix",
+    "ecs-dry": "php vendor/bin/ecs check",
+    "phplint": "php vendor/bin/phplint",
+    "phpstan": "php vendor/bin/phpstan analyse",
+    "rector-apply": "php vendor/bin/rector process --ansi",
+    "rector-dry": "php vendor/bin/rector process --dry-run --ansi",
+    "unittest": "php vendor/bin/phpunit --configuration phpunit.xml"
   },
-  "minimum-stability": "dev"
+  "minimum-stability": "stable"
 }

src/DataMapper.php

@@ -7,6 +7,7 @@
 use Exception;
 use Symfony\Component\HttpFoundation\Request;
 use Wundii\DataMapper\DataMapper as BaseDataMapper;
+use Wundii\DataMapper\Dto\CsvDto;
 use Wundii\DataMapper\Enum\SourceTypeEnum;
 use Wundii\DataMapper\Exception\DataMapperException;
 use Wundii\DataMapper\SymfonyBundle\Enum\MapStatusEnum;
@@ -35,16 +36,19 @@ public function getMapStatusEnum(): MapStatusEnum
      * @param class-string<T>|T $object
      * @param string[] $rootElementTree
      * @param bool $forceInstance // create a new instance, if no data can be found for the object
+     * @param string[] $options
      * @return ($object is class-string ? T : T[])
      */
     public function request(
         Request $request,
         string|object $object,
         array $rootElementTree = [],
         bool $forceInstance = false,
+        array $options = [],
     ): object|array {
         $content = $request->getContent();
         $sourceTypeEnum = match ($request->headers->get('Content-Type')) {
+            'application/csv', 'text/csv' => SourceTypeEnum::CSV,
             'application/json' => SourceTypeEnum::JSON,
             'application/neon', 'text/neon' => SourceTypeEnum::NEON,
             'application/xml', 'text/xml' => SourceTypeEnum::XML,
@@ -56,20 +60,34 @@ public function request(
             throw DataMapperException::InvalidArgument('No content provided in request');
         }
 
+        if ($sourceTypeEnum === SourceTypeEnum::CSV) {
+            $csvDto = new CsvDto(
+                $content,
+                $options['separator'] ?? CsvDto::DEFAULT_SEPARATOR,
+                $options['enclosure'] ?? CsvDto::DEFAULT_ENCLOSURE,
+                $options['escape'] ?? CsvDto::DEFAULT_ESCAPE,
+                (int) ($options['headerLine'] ?? CsvDto::DEFAULT_HEADER_LINE),
+                (int) ($options['firstLine'] ?? CsvDto::DEFAULT_FIRST_LINE),
+            );
+            $content = $csvDto;
+        }
+
         return $this->map($sourceTypeEnum, $content, $object, $rootElementTree, $forceInstance);
     }
 
     /**
      * @param class-string<T>|T $object
      * @param string[] $rootElementTree
      * @param bool $forceInstance // create a new instance, if no data can be found for the object
+     * @param string[] $options
      * @return ($object is class-string ? T : T[])
      */
     public function tryRequest(
         Request $request,
         string|object $object,
         array $rootElementTree = [],
         bool $forceInstance = false,
+        array $options = [],
     ): object|array|null {
         /**
          * reset error message
@@ -78,7 +96,7 @@ public function tryRequest(
 
         try {
             $this->mapStatusEnum = MapStatusEnum::SUCCESS;
-            return $this->request($request, $object, $rootElementTree, $forceInstance);
+            return $this->request($request, $object, $rootElementTree, $forceInstance, $options);
         } catch (Exception $exception) {
             $this->errorMessage = $exception->getMessage();
             $this->mapStatusEnum = MapStatusEnum::ERROR;

tests/DataMapperTest.php

@@ -262,4 +262,52 @@ public function testRequestWithEmptyContentTypeYamlAndForceInstance(): void
         $this->assertEquals(MapStatusEnum::ERROR, $this->dataMapper->getMapStatusEnum());
         $this->assertSame('Invalid Yaml decode return', $this->dataMapper->getErrorMessage());
     }
+
+    /**
+     * @throws Exception
+     */
+    public function testRequestWithValidContentTypeCsv(): void
+    {
+        $content = "string\ntest\n";
+        $object = TypeString::class;
+
+        $request = $this->getRequest('application/csv', $content);
+        $result = $this->dataMapper->tryRequest($request, $object);
+
+        $this->assertNull($this->dataMapper->getErrorMessage());
+        $this->assertEquals(MapStatusEnum::SUCCESS, $this->dataMapper->getMapStatusEnum());
+        $this->assertEquals([$this->expectedObject()], $result);
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function testRequestWithEmptyContentTypeCsv(): void
+    {
+        $content = '';
+        $object = TypeString::class;
+
+        $request = $this->getRequest('application/csv', $content);
+        $result = $this->dataMapper->tryRequest($request, $object);
+
+        $this->assertNull($result);
+        $this->assertEquals(MapStatusEnum::ERROR, $this->dataMapper->getMapStatusEnum());
+        $this->assertSame('No content provided in request', $this->dataMapper->getErrorMessage());
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function testRequestWithEmptyContentTypeCsvAndForceInstance(): void
+    {
+        $content = '';
+        $object = TypeString::class;
+
+        $request = $this->getRequest('application/csv', $content);
+        $result = $this->dataMapper->tryRequest($request, $object, [], true);
+
+        $this->assertNull($result);
+        $this->assertEquals(MapStatusEnum::ERROR, $this->dataMapper->getMapStatusEnum());
+        $this->assertStringContainsString('The file "" could not be written', $this->dataMapper->getErrorMessage());
+    }
 }