Option to return formatted dates instead of PHP objects (#226)

When reading spreadsheets, Spout should be able to return formatted dates, as shown when opened with Excel for instance.
It currently only returns DateTime/DateInterval objects, making it impossible to read + write, as the Writer does not accept objects.

tests/Spout/Reader/ODS/ReaderTest.php

@@ -164,6 +164,21 @@ class ReaderTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expectedRows, $allRows);
     }
 
+    /**
+     * @return void
+     */
+    public function testReadShouldSupportFormatDatesAndTimesIfSpecified()
+    {
+        $shouldFormatDates = true;
+        $allRows = $this->getAllRowsForFile('sheet_with_dates_and_times.ods', $shouldFormatDates);
+
+        $expectedRows = [
+            ['05/19/2016', '5/19/16', '05/19/2016 16:39:00', '05/19/16 04:39 PM', '5/19/2016'],
+            ['11:29', '13:23:45', '01:23:45', '01:23:45 AM', '01:23:45 PM'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
     /**
      * @return void
      */
@@ -455,14 +470,16 @@ class ReaderTest extends \PHPUnit_Framework_TestCase
 
     /**
      * @param string $fileName
+     * @param bool|void $shouldFormatDates
      * @return array All the read rows the given file
      */
-    private function getAllRowsForFile($fileName)
+    private function getAllRowsForFile($fileName, $shouldFormatDates = false)
     {
         $allRows = [];
         $resourcePath = $this->getResourcePath($fileName);
 
         $reader = ReaderFactory::create(Type::ODS);
+        $reader->setShouldFormatDates($shouldFormatDates);
         $reader->open($resourcePath);
 
         foreach ($reader->getSheetIterator() as $sheetIndex => $sheet) {

tests/Spout/Reader/XLSX/Helper/CellValueFormatterTest.php

@@ -71,7 +71,7 @@ class CellValueFormatterTest extends \PHPUnit_Framework_TestCase
             ->with(123)
             ->will($this->returnValue(true));
 
-        $formatter = new CellValueFormatter(null, $styleHelperMock);
+        $formatter = new CellValueFormatter(null, $styleHelperMock, false);
         $result = $formatter->extractAndFormatNodeValue($nodeMock);
 
         if ($expectedDateAsString === null) {
@@ -120,7 +120,7 @@ class CellValueFormatterTest extends \PHPUnit_Framework_TestCase
             ->method('shouldFormatNumericValueAsDate')
             ->will($this->returnValue(false));
 
-        $formatter = new CellValueFormatter(null, $styleHelperMock);
+        $formatter = new CellValueFormatter(null, $styleHelperMock, false);
         $formattedValue = \ReflectionHelper::callMethodOnObject($formatter, 'formatNumericCellValue', $value, 0);
 
         $this->assertEquals($expectedFormattedValue, $formattedValue);
@@ -163,7 +163,7 @@ class CellValueFormatterTest extends \PHPUnit_Framework_TestCase
             ->with(CellValueFormatter::XML_NODE_INLINE_STRING_VALUE)
             ->will($this->returnValue($nodeListMock));
 
-        $formatter = new CellValueFormatter(null, null);
+        $formatter = new CellValueFormatter(null, null, false);
         $formattedValue = \ReflectionHelper::callMethodOnObject($formatter, 'formatInlineStringCellValue', $nodeMock);
 
         $this->assertEquals($expectedFormattedValue, $formattedValue);

tests/Spout/Reader/XLSX/Helper/DateFormatHelperTest.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper;
+
+/**
+ * Class DateFormatHelperTest
+ *
+ * @package Box\Spout\Reader\XLSX\Helper
+ */
+class DateFormatHelperTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @return array
+     */
+    public function dataProviderForTestToPHPDateFormat()
+    {
+        return [
+            // Excel date format, expected PHP date format
+            ['m/d/yy hh:mm', 'n/j/y H:i'],
+            ['mmm-yy', 'M-y'],
+            ['d-mmm-yy', 'j-M-y'],
+            ['m/dd/yyyy', 'n/d/Y'],
+            ['e mmmmm dddd', 'Y M l'],
+            ['MMMM DDD', 'F D'],
+            ['hh:mm:ss.s', 'H:i:s'],
+            ['h:mm:ss AM/PM', 'g:i:s A'],
+            ['hh:mm AM/PM', 'h:i A'],
+            ['[$-409]hh:mm AM/PM', 'h:i A'],
+            ['[$USD-F480]hh:mm AM/PM', 'h:i A'],
+            ['"Day " d', '\\D\\a\\y\\  j'],
+            ['yy "Year" m "Month"', 'y \\Y\\e\\a\\r n \\M\\o\\n\\t\\h'],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestToPHPDateFormat
+     *
+     * @param string $excelDateFormat
+     * @param string $expectedPHPDateFormat
+     * @return void
+     */
+    public function testToPHPDateFormat($excelDateFormat, $expectedPHPDateFormat)
+    {
+        $phpDateFormat = DateFormatHelper::toPHPDateFormat($excelDateFormat);
+        $this->assertEquals($expectedPHPDateFormat, $phpDateFormat);
+    }
+}

tests/Spout/Reader/XLSX/ReaderTest.php

@@ -203,6 +203,21 @@ class ReaderTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expectedRows, $allRows);
     }
 
+    /**
+     * @return void
+     */
+    public function testReadShouldSupportFormatDatesAndTimesIfSpecified()
+    {
+        $shouldFormatDates = true;
+        $allRows = $this->getAllRowsForFile('sheet_with_dates_and_times.xlsx', $shouldFormatDates);
+
+        $expectedRows = [
+            ['1/13/2016', '01/13/2016', '13-Jan-16', 'Wednesday January 13, 16', 'Today is 1/13/2016'],
+            ['4:43:25', '04:43', '4:43', '4:43:25 AM', '4:43:25 PM'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
     /**
      * @return void
      */
@@ -503,14 +518,16 @@ class ReaderTest extends \PHPUnit_Framework_TestCase
 
     /**
      * @param string $fileName
+     * @param bool|void $shouldFormatDates
      * @return array All the read rows the given file
      */
-    private function getAllRowsForFile($fileName)
+    private function getAllRowsForFile($fileName, $shouldFormatDates = false)
     {
         $allRows = [];
         $resourcePath = $this->getResourcePath($fileName);
 
         $reader = ReaderFactory::create(Type::XLSX);
+        $reader->setShouldFormatDates($shouldFormatDates);
         $reader->open($resourcePath);
 
         foreach ($reader->getSheetIterator() as $sheetIndex => $sheet) {