Add helper functions to create specific readers and writers

Removed the `ReaderEntityFactory::createReader(Type)` method and replaced it by 3 methods:
- `ReaderEntityFactory::createCSVReader()`
- `ReaderEntityFactory::createXLSXReader()`
- `ReaderEntityFactory::createODSReader()`

This has the advantage of enabling autocomplete in the IDE, as the return type is no longer the interface but the concrete type. Since readers may expose different options, this is pretty useful.

Similarly, removed the `WriterEntityFactory::createWriter(Type)` method and replaced it by 3 methods:
- `WriterEntityFactory::createCSVWriter()`
- `WriterEntityFactory::createXLSXWriter()`
- `WriterEntityFactory::createODSWriter()`

Since this is a breaking change, I also updated the Upgrade guide.
Finally, the doc is up to date too.

src/Spout/Reader/Common/Creator/ReaderEntityFactory.php

@@ -2,6 +2,8 @@
 
 namespace Box\Spout\Reader\Common\Creator;
 
+use Box\Spout\Common\Exception\UnsupportedTypeException;
+use Box\Spout\Common\Type;
 use Box\Spout\Reader\ReaderInterface;
 
 /**
@@ -10,23 +12,10 @@ use Box\Spout\Reader\ReaderInterface;
  */
 class ReaderEntityFactory
 {
-    /**
-     * This creates an instance of the appropriate reader, given the type of the file to be read
-     *
-     * @param string $readerType Type of the reader to instantiate
-     * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
-     * @return ReaderInterface
-     */
-    public static function createReader($readerType)
-    {
-        return ReaderFactory::create($readerType);
-    }
-
     /**
      * Creates a reader by file extension
      *
      * @param string $path The path to the spreadsheet file. Supported extensions are .csv, .ods and .xlsx
-     * @throws \Box\Spout\Common\Exception\IOException
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      * @return ReaderInterface
      */
@@ -34,4 +23,46 @@ class ReaderEntityFactory
     {
         return ReaderFactory::createFromFile($path);
     }
+
+    /**
+     * This creates an instance of a CSV reader
+     *
+     * @return \Box\Spout\Reader\CSV\Reader
+     */
+    public static function createCSVReader()
+    {
+        try {
+            return ReaderFactory::createFromType(Type::CSV);
+        } catch (UnsupportedTypeException $e) {
+            // should never happen
+        }
+    }
+
+    /**
+     * This creates an instance of a XLSX reader
+     *
+     * @return \Box\Spout\Reader\XLSX\Reader
+     */
+    public static function createXLSXReader()
+    {
+        try {
+            return ReaderFactory::createFromType(Type::XLSX);
+        } catch (UnsupportedTypeException $e) {
+            // should never happen
+        }
+    }
+
+    /**
+     * This creates an instance of a ODS reader
+     *
+     * @return \Box\Spout\Reader\ODS\Reader
+     */
+    public static function createODSReader()
+    {
+        try {
+            return ReaderFactory::createFromType(Type::ODS);
+        } catch (UnsupportedTypeException $e) {
+            // should never happen
+        }
+    }
 }

src/Spout/Reader/Common/Creator/ReaderFactory.php

@@ -3,7 +3,6 @@
 namespace Box\Spout\Reader\Common\Creator;
 
 use Box\Spout\Common\Creator\HelperFactory;
-use Box\Spout\Common\Exception\IOException;
 use Box\Spout\Common\Exception\UnsupportedTypeException;
 use Box\Spout\Common\Type;
 use Box\Spout\Reader\CSV\Creator\InternalEntityFactory as CSVInternalEntityFactory;
@@ -30,14 +29,18 @@ use Box\Spout\Reader\XLSX\Reader as XLSXReader;
 class ReaderFactory
 {
     /**
-     * Map file extensions to reader types
-     * @var array
+     * Creates a reader by file extension
+     *
+     * @param string $path The path to the spreadsheet file. Supported extensions are .csv,.ods and .xlsx
+     * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
+     * @return ReaderInterface
      */
-    private static $extensionReaderMap = [
-        'csv' => Type::CSV,
-        'ods' => Type::ODS,
-        'xlsx' => Type::XLSX,
-    ];
+    public static function createFromFile(string $path)
+    {
+        $extension = strtolower(pathinfo($path, PATHINFO_EXTENSION));
+
+        return self::createFromType($extension);
+    }
 
     /**
      * This creates an instance of the appropriate reader, given the type of the file to be read
@@ -46,49 +49,21 @@ class ReaderFactory
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      * @return ReaderInterface
      */
-    public static function create($readerType)
+    public static function createFromType($readerType)
     {
         switch ($readerType) {
-            case Type::CSV: return self::getCSVReader();
-            case Type::XLSX: return self::getXLSXReader();
-            case Type::ODS: return self::getODSReader();
+            case Type::CSV: return self::createCSVReader();
+            case Type::XLSX: return self::createXLSXReader();
+            case Type::ODS: return self::createODSReader();
             default:
                 throw new UnsupportedTypeException('No readers supporting the given type: ' . $readerType);
         }
     }
 
-    /**
-     * Creates a reader by file extension
-     *
-     * @param string $path The path to the spreadsheet file. Supported extensions are .csv,.ods and .xlsx
-     * @throws \Box\Spout\Common\Exception\IOException
-     * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
-     * @return ReaderInterface
-     */
-    public static function createFromFile(string $path)
-    {
-        if (!is_file($path)) {
-            throw new IOException(
-                sprintf('Could not open "%s" for reading! File does not exist.', $path)
-            );
-        }
-
-        $ext = pathinfo($path, PATHINFO_EXTENSION);
-        $ext = strtolower($ext);
-        $readerType = self::$extensionReaderMap[$ext] ?? null;
-        if ($readerType === null) {
-            throw new UnsupportedTypeException(
-                sprintf('No readers supporting the file extension "%s".', $ext)
-            );
-        }
-
-        return self::create($readerType);
-    }
-
     /**
      * @return CSVReader
      */
-    private static function getCSVReader()
+    private static function createCSVReader()
     {
         $optionsManager = new CSVOptionsManager();
         $helperFactory = new HelperFactory();
@@ -101,7 +76,7 @@ class ReaderFactory
     /**
      * @return XLSXReader
      */
-    private static function getXLSXReader()
+    private static function createXLSXReader()
     {
         $optionsManager = new XLSXOptionsManager();
         $helperFactory = new XLSXHelperFactory();
@@ -115,7 +90,7 @@ class ReaderFactory
     /**
      * @return ODSReader
      */
-    private static function getODSReader()
+    private static function createODSReader()
     {
         $optionsManager = new ODSOptionsManager();
         $helperFactory = new ODSHelperFactory();

src/Spout/Writer/Common/Creator/WriterEntityFactory.php

@@ -5,6 +5,8 @@ namespace Box\Spout\Writer\Common\Creator;
 use Box\Spout\Common\Entity\Cell;
 use Box\Spout\Common\Entity\Row;
 use Box\Spout\Common\Entity\Style\Style;
+use Box\Spout\Common\Exception\UnsupportedTypeException;
+use Box\Spout\Common\Type;
 use Box\Spout\Writer\WriterInterface;
 
 /**
@@ -22,14 +24,13 @@ class WriterEntityFactory
      */
     public static function createWriter($writerType)
     {
-        return WriterFactory::create($writerType);
+        return WriterFactory::createFromType($writerType);
     }
 
     /**
      * This creates an instance of the appropriate writer, given the extension of the file to be written
      *
      * @param string $path The path to the spreadsheet file. Supported extensions are .csv, .ods and .xlsx
-     * @throws \Box\Spout\Common\Exception\IOException
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      * @return WriterInterface
      */
@@ -38,6 +39,48 @@ class WriterEntityFactory
         return WriterFactory::createFromFile($path);
     }
 
+    /**
+     * This creates an instance of a CSV writer
+     *
+     * @return \Box\Spout\Writer\CSV\Writer
+     */
+    public static function createCSVWriter()
+    {
+        try {
+            return WriterFactory::createFromType(Type::CSV);
+        } catch (UnsupportedTypeException $e) {
+            // should never happen
+        }
+    }
+
+    /**
+     * This creates an instance of a XLSX writer
+     *
+     * @return \Box\Spout\Writer\XLSX\Writer
+     */
+    public static function createXLSXWriter()
+    {
+        try {
+            return WriterFactory::createFromType(Type::XLSX);
+        } catch (UnsupportedTypeException $e) {
+            // should never happen
+        }
+    }
+
+    /**
+     * This creates an instance of a ODS writer
+     *
+     * @return \Box\Spout\Writer\ODS\Writer
+     */
+    public static function createODSWriter()
+    {
+        try {
+            return WriterFactory::createFromType(Type::ODS);
+        } catch (UnsupportedTypeException $e) {
+            // should never happen
+        }
+    }
+
     /**
      * @param Cell[] $cells
      * @param Style|null $rowStyle

src/Spout/Writer/Common/Creator/WriterFactory.php

@@ -3,7 +3,6 @@
 namespace Box\Spout\Writer\Common\Creator;
 
 use Box\Spout\Common\Creator\HelperFactory;
-use Box\Spout\Common\Exception\IOException;
 use Box\Spout\Common\Exception\UnsupportedTypeException;
 use Box\Spout\Common\Helper\GlobalFunctionsHelper;
 use Box\Spout\Common\Type;
@@ -28,65 +27,41 @@ use Box\Spout\Writer\XLSX\Writer as XLSXWriter;
 class WriterFactory
 {
     /**
-     * Map file extensions to reader types
-     * @var array
-     */
-    private static $extensionReaderMap = [
-        'csv' => Type::CSV,
-        'ods' => Type::ODS,
-        'xlsx' => Type::XLSX,
-    ];
-
-    /**
-     * This creates an instance of the appropriate writer, given the type of the file to be read
+     * This creates an instance of the appropriate writer, given the extension of the file to be written
      *
-     * @param  string $writerType Type of the writer to instantiate
+     * @param string $path The path to the spreadsheet file. Supported extensions are .csv,.ods and .xlsx
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      * @return WriterInterface
      */
-    public static function create($writerType)
+    public static function createFromFile(string $path)
+    {
+        $extension = strtolower(pathinfo($path, PATHINFO_EXTENSION));
+
+        return self::createFromType($extension);
+    }
+
+    /**
+     * This creates an instance of the appropriate writer, given the type of the file to be written
+     *
+     * @param string $writerType Type of the writer to instantiate
+     * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
+     * @return WriterInterface
+     */
+    public static function createFromType($writerType)
     {
         switch ($writerType) {
-            case Type::CSV: return self::getCSVWriter();
-            case Type::XLSX: return self::getXLSXWriter();
-            case Type::ODS: return self::getODSWriter();
+            case Type::CSV: return self::createCSVWriter();
+            case Type::XLSX: return self::createXLSXWriter();
+            case Type::ODS: return self::createODSWriter();
             default:
                 throw new UnsupportedTypeException('No writers supporting the given type: ' . $writerType);
         }
     }
 
-    /**
-     * This creates an instance of the appropriate writer, given the extension of the file to be written
-     *
-     * @param string $path The path to the spreadsheet file. Supported extensions are .csv,.ods and .xlsx
-     * @throws \Box\Spout\Common\Exception\IOException
-     * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
-     * @return WriterInterface
-     */
-    public static function createFromFile(string $path)
-    {
-        if (!is_file($path)) {
-            throw new IOException(
-                sprintf('Could not open "%s" for reading! File does not exist.', $path)
-            );
-        }
-
-        $ext = pathinfo($path, PATHINFO_EXTENSION);
-        $ext = strtolower($ext);
-        $readerType = self::$extensionReaderMap[$ext] ?? null;
-        if ($readerType === null) {
-            throw new UnsupportedTypeException(
-                sprintf('No readers supporting the file extension "%s".', $ext)
-            );
-        }
-
-        return self::create($readerType);
-    }
-
     /**
      * @return CSVWriter
      */
-    private static function getCSVWriter()
+    private static function createCSVWriter()
     {
         $optionsManager = new CSVOptionsManager();
         $globalFunctionsHelper = new GlobalFunctionsHelper();
@@ -99,7 +74,7 @@ class WriterFactory
     /**
      * @return XLSXWriter
      */
-    private static function getXLSXWriter()
+    private static function createXLSXWriter()
     {
         $styleBuilder = new StyleBuilder();
         $optionsManager = new XLSXOptionsManager($styleBuilder);
@@ -114,7 +89,7 @@ class WriterFactory
     /**
      * @return ODSWriter
      */
-    private static function getODSWriter()
+    private static function createODSWriter()
     {
         $styleBuilder = new StyleBuilder();
         $optionsManager = new ODSOptionsManager($styleBuilder);