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.
selay · May 17, 2019 · 40ee386 · 40ee386
1 parent 6104d41
commit 40ee386
Show file tree

Hide file tree

Showing 30 changed files with 228 additions and 268 deletions.
diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md
@@ -15,11 +15,14 @@ Finally, **_Spout 3.0 only supports PHP 7.1 and above_**, as other PHP versions
 
 Reader changes
 --------------
-Creating a reader should now be done through the Reader `ReaderEntityFactory`, instead of using the `ReaderFactory`:
+Creating a reader should now be done through the Reader `ReaderEntityFactory`, instead of using the `ReaderFactory`.
+Also, the `ReaderFactory::create($type)` method was removed and replaced by methods for each reader:
 ```php
 use Box\Spout\Reader\Common\Creator\ReaderEntityFactory; // namespace is no longer "Box\Spout\Reader"
 ...
-$reader = ReaderEntityFactory::createReader(Type::XLSX);
+$reader = ReaderEntityFactory::createXLSXReader(); // replaces ReaderFactory::create(Type::XLSX)
+$reader = ReaderEntityFactory::createCSVReader();  // replaces ReaderFactory::create(Type::CSV)
+$reader = ReaderEntityFactory::createODSReader();  // replaces ReaderFactory::create(Type::ODS)
 ```
 
 When iterating over the spreadsheet rows, Spout now returns `Row` objects, instead of an array containing row values. Accessing the row values should now be done this way:
@@ -37,11 +40,15 @@ foreach ($reader->getSheetIterator() as $sheet) {
 
 Writer changes
 --------------
-Writer creation follows the same change as the reader. It should now be done through the Writer `WriterEntityFactory`, instead of using the `WriterFactory`:
+Writer creation follows the same change as the reader. It should now be done through the Writer `WriterEntityFactory`, instead of using the `WriterFactory`.
+Also, the `WriterFactory::create($type)` method was removed and replaced by methods for each writer:
+
 ```php
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory; // namespace is no longer "Box\Spout\Writer"
 ...
-$writer = WriterEntityFactory::createWriter(Type::ODS);
+$writer = WriterEntityFactory::createXLSXWriter(); // replaces WriterFactory::create(Type::XLSX)
+$writer = WriterEntityFactory::createCSVWriter();  // replaces WriterFactory::create(Type::CSV)
+$writer = WriterEntityFactory::createODSWriter();  // replaces WriterFactory::create(Type::ODS)
 ```
 
 Adding rows is also done differently: instead of passing an array, the writer now takes in a `Row` object (or an array of `Row`). Creating such objects can easily be done this way:

diff --git a/docs/_pages/documentation.md b/docs/_pages/documentation.md
@@ -44,9 +44,8 @@ It is possible to change the behavior of the writers when the maximum number of
 ```php
 
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
-use Box\Spout\Common\Type;
 
-$writer = WriterEntityFactory::createWriter(Type::ODS);
+$writer = WriterEntityFactory::createODSWriter();
 $writer->setShouldCreateNewSheetsAutomatically(true); // default value
 $writer->setShouldCreateNewSheetsAutomatically(false); // will stop writing new data when limit is reached
 ```
@@ -57,9 +56,8 @@ Processing XLSX and ODS files requires temporary files to be created. By default
 
 ```php
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
-use Box\Spout\Common\Type;
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
+$writer = WriterEntityFactory::createXLSXWriter();
 $writer->setTempFolder($customTempFolderPath);
 ```
 
@@ -73,9 +71,8 @@ In order to keep the memory usage really low, {{ site.spout_html }} does not de-
 
 ```php
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
-use Box\Spout\Common\Type;
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
+$writer = WriterEntityFactory::createXLSXWriter();
 $writer->setShouldUseInlineStrings(true); // default (and recommended) value
 $writer->setShouldUseInlineStrings(false); // will use shared strings
 ```
@@ -91,9 +88,8 @@ It is possible to change this behavior and have a formatted date returned instea
 
 ```php
 use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;
-use Box\Spout\Common\Type;
 
-$reader = ReaderEntityFactory::createReader(Type::XLSX);
+$reader = ReaderEntityFactory::createXLSXReader();
 $reader->setShouldFormatDates(false); // default value
 $reader->setShouldFormatDates(true); // will return formatted dates
 ```
@@ -137,12 +133,11 @@ For fonts and alignments, {{ site.spout_html }} does not support all the possibl
 It is possible to apply some formatting options to a row. In this case, all cells of the row will have the same style:
 
 ```php
-use Box\Spout\Common\Type;
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
 use Box\Spout\Writer\Common\Creator\Style\StyleBuilder;
 use Box\Spout\Common\Entity\Style\Color;
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
+$writer = WriterEntityFactory::createXLSXWriter();
 $writer->openToFile($filePath);
 
 /** Create a style with the StyleBuilder */
@@ -165,7 +160,6 @@ $writer->close();
 Adding borders to a row requires a ```Border``` object.
 
 ```php
-use Box\Spout\Common\Type;
 use Box\Spout\Common\Entity\Style\Border;
 use Box\Spout\Writer\Common\Creator\Style\BorderBuilder;
 use Box\Spout\Common\Entity\Style\Color;
@@ -180,7 +174,7 @@ $style = (new StyleBuilder())
     ->setBorder($border)
     ->build();
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
+$writer = WriterEntityFactory::createXLSXWriter();
 $writer->openToFile($filePath);
 
 $cells = WriterEntityFactory::createCell('Border Bottom Green Thin Dashed');
@@ -202,7 +196,6 @@ The styles applied to a specific cell will override any parent styles if present
 Example:
 
 ```php
-use Box\Spout\Common\Type;
 use Box\Spout\Common\Entity\Style\Color;
 use Box\Spout\Writer\Common\Creator\Style\StyleBuilder;
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
@@ -211,7 +204,7 @@ $defaultStyle = (new StyleBuilder())
     ->setFontSize(8)
     ->build();
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
+$writer = WriterEntityFactory::createXLSXWriter();
 $writer->setDefaultRowStyle($defaultStyle)
     ->openToFile($filePath);
 
@@ -252,7 +245,7 @@ $defaultStyle = (new StyleBuilder())
                 ->setFontSize(11)
                 ->build();
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
+$writer = WriterEntityFactory::createXLSXWriter();
 $writer->setDefaultRowStyle($defaultStyle)
        ->openToFile($filePath);
 ```

diff --git a/docs/_pages/getting-started.md b/docs/_pages/getting-started.md
@@ -68,16 +68,14 @@ $reader->close();
 If there are multiple sheets in the file, the reader will read all of them sequentially.
 
 
-Note that {{ site.spout_html }} guesses the reader type based on the file extension. If the extension is not standard (`.csv`, `.ods`, `.xlsx` _- lower/uppercase_), the reader type needs to be specified:
+Note that {{ site.spout_html }} guesses the reader type based on the file extension. If the extension is not standard (`.csv`, `.ods`, `.xlsx` _- lower/uppercase_), a specific reader can be created directly:
 
 ```php
-
 use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;
-use Box\Spout\Common\Type;
 
-$reader = ReaderEntityFactory::createReader(Type::XLSX); // for XLSX files
-// $reader = ReaderEntityFactory::createReader(Type::ODS); // for ODS files
-// $reader = ReaderEntityFactory::createReader(Type::CSV); // for CSV files
+$reader = ReaderEntityFactory::createXLSXReader();
+// $reader = ReaderEntityFactory::createODSReader();
+// $reader = ReaderEntityFactory::createCSVReader();
 ```
 
 ### Writer
@@ -124,9 +122,9 @@ Similar to the reader, if the file extension of the file to be written is not st
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
 use Box\Spout\Common\Entity\Row;
 
-$writer = WriterEntityFactory::createWriter(Type::XLSX);
-// $writer = WriterEntityFactory::createWriter(Type::ODS);
-// $writer = WriterEntityFactory::createWriter(Type::CSV);
+$writer = WriterEntityFactory::createXLSXWriter();
+// $writer = WriterEntityFactory::createODSWriter();
+// $writer = WriterEntityFactory::createCSVWriter();
 ```
 
 For XLSX and ODS files, the number of rows per sheet is limited to *1,048,576*. By default, once this limit is reached, the writer will automatically create a new sheet and continue writing data into it.

diff --git a/docs/_pages/guides/3-read-data-from-specific-sheet.md b/docs/_pages/guides/3-read-data-from-specific-sheet.md
@@ -12,10 +12,9 @@ Even though a spreadsheet contains multiple sheets, you may be interested in rea
 ```php
 <?php
 
-use Box\Spout\Common\Type;
 use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;
 
-$reader = ReaderEntityFactory::createReader(Type::XLSX);
+$reader = ReaderEntityFactory::createXLSXReader();
 $reader->open($filePath);
 
 foreach ($reader->getSheetIterator() as $sheet) {
@@ -36,10 +35,9 @@ $reader->close();
 ```php
 <?php
 
-use Box\Spout\Common\Type;
 use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;
 
-$reader = ReaderEntityFactory::createReader(Type::XLSX);
+$reader = ReaderEntityFactory::createXLSXReader();
 $reader->open($filePath);
 
 foreach ($reader->getSheetIterator() as $sheet) {

diff --git a/docs/_pages/guides/4-symfony-stream-content-large-spreadsheet.md b/docs/_pages/guides/4-symfony-stream-content-large-spreadsheet.md
@@ -77,7 +77,7 @@ class MyStreamController extends Controller
         // a callback function to retrieve data chunks.
         $response->setCallback(function() use ($filePath) {
             // Same code goes inside the callback.
-            $reader = ReaderEntityFactory::createReader(Type::XLSX);
+            $reader = ReaderEntityFactory::createXLSXReader();
             $reader->open($filePath);
 
             $i = 0;

diff --git a/src/Spout/Reader/Common/Creator/ReaderEntityFactory.php b/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;
 
 /**
@@ -11,27 +13,56 @@
 class ReaderEntityFactory
 {
     /**
-     * This creates an instance of the appropriate reader, given the type of the file to be read
+     * Creates a reader by file extension
      *
-     * @param string $readerType Type of the reader 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 ReaderInterface
      */
-    public static function createReader($readerType)
+    public static function createReaderFromFile(string $path)
     {
-        return ReaderFactory::create($readerType);
+        return ReaderFactory::createFromFile($path);
     }
 
     /**
-     * Creates a reader by file extension
+     * This creates an instance of a CSV reader
      *
-     * @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
+     * @return \Box\Spout\Reader\CSV\Reader
      */
-    public static function createReaderFromFile(string $path)
+    public static function createCSVReader()
     {
-        return ReaderFactory::createFromFile($path);
+        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
+        }
     }
 }
diff --git a/src/Spout/Reader/Common/Creator/ReaderFactory.php b/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,65 +29,41 @@
 class ReaderFactory
 {
     /**
-     * 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 reader, given the type of the file to be read
+     * Creates a reader by file extension
      *
-     * @param  string $readerType Type of the reader 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 ReaderInterface
      */
-    public static function create($readerType)
+    public static function createFromFile(string $path)
     {
-        switch ($readerType) {
-            case Type::CSV: return self::getCSVReader();
-            case Type::XLSX: return self::getXLSXReader();
-            case Type::ODS: return self::getODSReader();
-            default:
-                throw new UnsupportedTypeException('No readers supporting the given type: ' . $readerType);
-        }
+        $extension = strtolower(pathinfo($path, PATHINFO_EXTENSION));
+
+        return self::createFromType($extension);
     }
 
     /**
-     * Creates a reader by file extension
+     * This creates an instance of the appropriate reader, given the type of the file to be read
      *
-     * @param string $path The path to the spreadsheet file. Supported extensions are .csv,.ods and .xlsx
-     * @throws \Box\Spout\Common\Exception\IOException
+     * @param  string $readerType Type of the reader to instantiate
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      * @return ReaderInterface
      */
-    public static function createFromFile(string $path)
+    public static function createFromType($readerType)
     {
-        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)
-            );
+        switch ($readerType) {
+            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);
         }
-
-        return self::create($readerType);
     }
 
     /**
      * @return CSVReader
      */
-    private static function getCSVReader()
+    private static function createCSVReader()
     {
         $optionsManager = new CSVOptionsManager();
         $helperFactory = new HelperFactory();
@@ -101,7 +76,7 @@ private static function getCSVReader()
     /**
      * @return XLSXReader
      */
-    private static function getXLSXReader()
+    private static function createXLSXReader()
     {
         $optionsManager = new XLSXOptionsManager();
         $helperFactory = new XLSXHelperFactory();
@@ -115,7 +90,7 @@ private static function getXLSXReader()
     /**
      * @return ODSReader
      */
-    private static function getODSReader()
+    private static function createODSReader()
     {
         $optionsManager = new ODSOptionsManager();
         $helperFactory = new ODSHelperFactory();