Merge pull request #77 from box/fix_csv_reader_empty_last_line

Fix CSV reader when last line is empty

.gitignore

@@ -1,6 +1,5 @@
 /tests/resources/generated
 /tests/coverage
 /vendor
-composer.lock
 /.idea
 *.iml

.scrutinizer.yml

@@ -0,0 +1,54 @@
+filter:
+    excluded_paths: [vendor/*, tests/*]
+
+tools:
+    external_code_coverage:
+        timeout: 600 # Wait 10 minutes for results
+        runs: 3 # Merge results for 5.4, 5.5 and 5.6 jobs
+    php_mess_detector: true
+    php_code_sniffer:
+        config:
+            standard: PSR4
+        filter:
+            paths: ['src']
+    sensiolabs_security_checker: true
+    php_pdepend: true
+    php_loc:
+        enabled: true
+        excluded_dirs: [vendor, tests]
+    php_cpd:
+        enabled: true
+        excluded_dirs: [vendor, tests]
+
+build_failure_conditions:
+    - 'project.metric("scrutinizer.quality", < 9)' # Code Quality Rating drops below 9
+    - 'project.metric_change("scrutinizer.test_coverage", < -0.005)' # Code Coverage decreased by more than 0.5%
+    - 'project.metric("scrutinizer.test_coverage", < 0.97)' # Code Coverage drops below 97%
+
+checks:
+    php:
+        remove_extra_empty_lines: true
+        remove_php_closing_tag: true
+        remove_trailing_whitespace: true
+        fix_use_statements:
+            remove_unused: true
+            preserve_multiple: false
+            preserve_blanklines: true
+        fix_php_opening_tag: true
+        fix_linefeed: true
+        fix_line_ending: true
+        fix_identation_4spaces: true
+        fix_doc_comments: true
+        uppercase_constants: true
+        use_self_instead_of_fqcn: true
+        simplify_boolean_return: true
+        return_doc_comments: true
+        return_doc_comment_if_not_inferrable: true
+        phpunit_assertions: true
+        parameters_in_camelcaps: true
+        parameter_doc_comments: true
+        param_doc_comment_if_not_inferrable: true
+        optional_parameters_at_the_end: true
+        newline_at_end_of_file: true
+        encourage_single_quotes: true
+

.travis.yml

@@ -4,11 +4,15 @@ php:
   - 5.4
   - 5.5
   - 5.6
-  - nightly
+  - 7.0
   - hhvm
 
 install:
-  - composer self-update
-  - composer install --prefer-source
+  - composer install --no-interaction --prefer-source
 
-script: phpunit
+script:
+  - mkdir -p build/logs
+  - php vendor/bin/phpunit --coverage-clover build/logs/clover.xml
+
+after_script:
+  - if [[ $TRAVIS_PHP_VERSION != 'hhvm' && $TRAVIS_PHP_VERSION != '7.0' ]]; then php vendor/bin/ocular code-coverage:upload --format=php-clover build/logs/clover.xml; fi

README.md

@@ -2,8 +2,10 @@
 
 [![Latest Stable Version](https://poser.pugx.org/box/spout/v/stable)](https://packagist.org/packages/box/spout)
 [![Project Status](http://opensource.box.com/badges/active.svg)](http://opensource.box.com/badges)
-[![Build Status](https://travis-ci.org/box/spout.png?branch=master)](http://travis-ci.org/box/spout)
-[![Total Downloads](https://poser.pugx.org/box/spout/downloads)](https://packagist.org/packages/box/spout) [![License](https://poser.pugx.org/box/spout/license)](https://packagist.org/packages/box/spout)
+[![Build Status](https://travis-ci.org/box/spout.svg?branch=master)](http://travis-ci.org/box/spout)
+[![Code Coverage](https://scrutinizer-ci.com/g/box/spout/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/box/spout/?branch=master)
+[![Total Downloads](https://poser.pugx.org/box/spout/downloads)](https://packagist.org/packages/box/spout)
+[![License](https://poser.pugx.org/box/spout/license)](https://packagist.org/packages/box/spout)
 
 Spout is a PHP library to read and write CSV and XLSX files, in a fast and scalable way.
 Contrary to other file readers or writers, it is capable of processing very large files while keeping the memory usage really low (less than 10MB).
@@ -11,12 +13,14 @@ Contrary to other file readers or writers, it is capable of processing very larg
 
 ## Installation
 
-The Spout library can be installed directly from [Composer](https://getcomposer.org/).
+### Composer (recommended)
+
+Spout can be installed directly from [Composer](https://getcomposer.org/).
 
 Add "box/spout" as a dependency in your project's composer.json file:
 ```json
 "require": {
-    "box/spout": "*"
+    "box/spout": "~2.0"
 }
 ```
 
@@ -25,6 +29,19 @@ Then run the install command from Composer:
 php composer.phar install
 ```
 
+### Manual installation
+
+If you can't use Composer, no worries! You can still install Spout manually.
+
+> Before starting, make sure your system meets the [requirements](#requirements).
+
+1. Download the source code from the [Releases page](https://github.com/box/spout/releases)
+2. Extract the downloaded content into your project.
+3. Add this code to the top controller (index.php) or wherever it may be more appropriate:
+```php
+require_once '[PATH/TO]/src/Spout/Autoloader/autoload.php'; // don't forget to change the path!
+```
+
 
 ## Requirements
 
@@ -47,9 +64,10 @@ use Box\Spout\Common\Type;
 $reader = ReaderFactory::create(Type::CSV);
 $reader->open($filePath);
 
-while ($reader->hasNextRow()) {
-    $row = $reader->nextRow();
-    // do stuff
+foreach ($reader->getSheetIterator() as $sheet) {
+    foreach ($reader->getRowIterator() as $row) {
+        // do stuff
+    }
 }
 
 $reader->close();
@@ -64,11 +82,8 @@ use Box\Spout\Common\Type;
 $reader = ReaderFactory::create(Type::XLSX);
 $reader->open($filePath);
 
-while ($reader->hasNextSheet()) {
-    $reader->nextSheet();
-
-    while ($reader->hasNextRow()) {
-        $row = $reader->nextRow();
+foreach ($reader->getSheetIterator() as $sheet) {
+    foreach ($reader->getRowIterator() as $row) {
         // do stuff
     }
 }
@@ -111,7 +126,7 @@ For XLSX files, the number of rows per sheet is limited to 1,048,576 (see [Offic
 
 ### Configuring the CSV reader and writer
 
-It is possible to configure the both the CSV reader and writer to specify the field separator as well as the field enclosure:
+It is possible to configure both the CSV reader and writer to specify the field separator as well as the field enclosure:
 ```php
 use Box\Spout\Reader\ReaderFactory;
 use Box\Spout\Common\Type;
@@ -121,6 +136,13 @@ $reader->setFieldDelimiter('|');
 $reader->setFieldEnclosure('@');
 ```
 
+Additionally, if you need to read non UTF-8 files, you can specify the encoding of your file this way:
+```php
+$reader->setEncoding('UTF-16LE');
+```
+
+The writer always generate CSV files encoded in UTF-8, with a BOM.
+
 ### Configuring the XLSX writer
 
 #### Strings storage
@@ -185,8 +207,7 @@ $sheets = $writer->getSheets();
 If you rely on the sheet's name in your application, you can access it and customize it this way:
 ```php
 // Accessing the sheet name when reading
-while ($reader->hasNextSheet()) {
-    $sheet = $reader->nextSheet();
+foreach ($reader->getSheetIterator() as $sheet) {
     $sheetName = $sheet->getName();
 }
 
@@ -236,7 +257,7 @@ For information, the performance tests take about one hour to run (processing 2
 
 When writing data, Spout is streaming the data to files, one or few lines at a time. That means that it only keeps in memory the few rows that it needs to write. Once written, the memory is freed.
 
-Same goes with reading. Only one row at a time is stored in memory. A special technique is used to handle shared strings in XLSX, storing them into several small temporary files that allows fast access.
+Same goes with reading. Only one row at a time is stored in memory. A special technique is used to handle shared strings in XLSX, storing them - if needed - into several small temporary files that allows fast access.
 
 #### How long does it take to generate a file with X rows?
 

composer.json

@@ -2,7 +2,6 @@
     "name": "box/spout",
     "description": "PHP Library to read and write CSV and XLSX files, in a fast and scalable way",
     "type": "library",
-    "version": "1.0.9",
     "keywords": ["php","read","write","csv","xlsx","excel","spreadsheet","scale","memory","stream","ooxml"],
     "license": "Apache-2.0",
     "homepage": "https://www.github.com/box/spout",
@@ -19,7 +18,12 @@
         "ext-simplexml": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": ">=3.7"
+        "phpunit/phpunit": ">=3.7",
+        "scrutinizer/ocular": "~1.1"
+    },
+    "suggest": {
+        "ext-iconv": "To handle non UTF-8 CSV files (if \"php-intl\" is not already installed or is too limited)",
+        "ext-intl": "To handle non UTF-8 CSV files (if \"iconv\" is not already installed)"
     },
     "autoload": {
         "psr-4": {

phpunit.xml

@@ -5,7 +5,6 @@
         colors="true"
         convertErrorsToExceptions="false"
         convertWarningsToExceptions="false"
-        strict="false"
         verbose="false">
 
     <testsuites>
@@ -14,13 +13,12 @@
         </testsuite>
     </testsuites>
 
-    <logging>
-        <log type="coverage-html" target="tests/coverage/"/>
-    </logging>
-
     <filter>
         <whitelist>
             <directory suffix=".php">src/</directory>
+            <exclude>
+                <directory>src/Spout/Autoloader</directory>
+            </exclude>
         </whitelist>
     </filter>
 

src/Spout/Autoloader/Psr4Autoloader.php

@@ -0,0 +1,150 @@
+<?php
+
+namespace Box\Spout\Autoloader;
+
+/**
+ * Class Psr4Autoloader
+ * @see https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader-examples.md#class-example
+ *
+ * @package Box\Spout\Autoloader
+ */
+class Psr4Autoloader
+{
+    /**
+     * An associative array where the key is a namespace prefix and the value
+     * is an array of base directories for classes in that namespace.
+     *
+     * @var array
+     */
+    protected $prefixes = array();
+
+    /**
+     * Register loader with SPL autoloader stack.
+     *
+     * @return void
+     */
+    public function register()
+    {
+        spl_autoload_register(array($this, 'loadClass'));
+    }
+
+    /**
+     * Adds a base directory for a namespace prefix.
+     *
+     * @param string $prefix The namespace prefix.
+     * @param string $baseDir A base directory for class files in the
+     * namespace.
+     * @param bool $prepend If true, prepend the base directory to the stack
+     * instead of appending it; this causes it to be searched first rather
+     * than last.
+     * @return void
+     */
+    public function addNamespace($prefix, $baseDir, $prepend = false)
+    {
+        // normalize namespace prefix
+        $prefix = trim($prefix, '\\') . '\\';
+
+        // normalize the base directory with a trailing separator
+        $baseDir = rtrim($baseDir, DIRECTORY_SEPARATOR) . '/';
+
+        // initialize the namespace prefix array
+        if (isset($this->prefixes[$prefix]) === false) {
+            $this->prefixes[$prefix] = array();
+        }
+
+        // retain the base directory for the namespace prefix
+        if ($prepend) {
+            array_unshift($this->prefixes[$prefix], $baseDir);
+        } else {
+            array_push($this->prefixes[$prefix], $baseDir);
+        }
+    }
+
+    /**
+     * Loads the class file for a given class name.
+     *
+     * @param string $class The fully-qualified class name.
+     * @return mixed The mapped file name on success, or boolean false on
+     * failure.
+     */
+    public function loadClass($class)
+    {
+        // the current namespace prefix
+        $prefix = $class;
+
+        // work backwards through the namespace names of the fully-qualified
+        // class name to find a mapped file name
+        while (false !== $pos = strrpos($prefix, '\\')) {
+
+            // retain the trailing namespace separator in the prefix
+            $prefix = substr($class, 0, $pos + 1);
+
+            // the rest is the relative class name
+            $relativeClass = substr($class, $pos + 1);
+
+            // try to load a mapped file for the prefix and relative class
+            $mappedFile = $this->loadMappedFile($prefix, $relativeClass);
+            if ($mappedFile !== false) {
+                return $mappedFile;
+            }
+
+            // remove the trailing namespace separator for the next iteration
+            // of strrpos()
+            $prefix = rtrim($prefix, '\\');
+        }
+
+        // never found a mapped file
+        return false;
+    }
+
+    /**
+     * Load the mapped file for a namespace prefix and relative class.
+     *
+     * @param string $prefix The namespace prefix.
+     * @param string $relativeClass The relative class name.
+     * @return mixed Boolean false if no mapped file can be loaded, or the
+     * name of the mapped file that was loaded.
+     */
+    protected function loadMappedFile($prefix, $relativeClass)
+    {
+        // are there any base directories for this namespace prefix?
+        if (isset($this->prefixes[$prefix]) === false) {
+            return false;
+        }
+
+        // look through base directories for this namespace prefix
+        foreach ($this->prefixes[$prefix] as $baseDir) {
+
+            // replace the namespace prefix with the base directory,
+            // replace namespace separators with directory separators
+            // in the relative class name, append with .php
+            $file = $baseDir
+                  . str_replace('\\', '/', $relativeClass)
+                  . '.php';
+
+            // if the mapped file exists, require it
+            if ($this->requireFile($file)) {
+                // yes, we're done
+                return $file;
+            }
+        }
+
+        // never found it
+        return false;
+    }
+
+    /**
+     * If a file exists, require it from the file system.
+     *
+     * @param string $file The file to require.
+     * @return bool True if the file exists, false if not.
+     */
+    protected function requireFile($file)
+    {
+        if (file_exists($file)) {
+            require $file;
+            return true;
+        }
+        return false;
+    }
+}

src/Spout/Autoloader/autoload.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Box\Spout\Autoloader;
+
+require_once 'Psr4Autoloader.php';
+
+/**
+ * @var string $srcBaseDirectory
+ * Full path to "src/Spout" which is what we want "Box\Spout" to map to.
+ */
+$srcBaseDirectory = dirname(dirname(__FILE__));
+
+$loader = new Psr4Autoloader();
+$loader->register();
+$loader->addNamespace('Box\Spout', $srcBaseDirectory);

src/Spout/Common/Exception/EncodingConversionException.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Box\Spout\Common\Exception;
+
+/**
+ * Class EncodingConversionException
+ *
+ * @package Box\Spout\Common\Exception
+ */
+class EncodingConversionException extends SpoutException
+{
+}

src/Spout/Common/Helper/EncodingHelper.php

@@ -0,0 +1,175 @@
+<?php
+
+namespace Box\Spout\Common\Helper;
+
+use Box\Spout\Common\Exception\EncodingConversionException;
+
+/**
+ * Class EncodingHelper
+ * This class provides helper functions to work with encodings.
+ *
+ * @package Box\Spout\Common\Helper
+ */
+class EncodingHelper
+{
+    /** Definition of the encodings that can have a BOM */
+    const ENCODING_UTF8     = 'UTF-8';
+    const ENCODING_UTF16_LE = 'UTF-16LE';
+    const ENCODING_UTF16_BE = 'UTF-16BE';
+    const ENCODING_UTF32_LE = 'UTF-32LE';
+    const ENCODING_UTF32_BE = 'UTF-32BE';
+
+    /** Definition of the BOMs for the different encodings */
+    const BOM_UTF8     = "\xEF\xBB\xBF";
+    const BOM_UTF16_LE = "\xFF\xFE";
+    const BOM_UTF16_BE = "\xFE\xFF";
+    const BOM_UTF32_LE = "\xFF\xFE\x00\x00";
+    const BOM_UTF32_BE = "\x00\x00\xFE\xFF";
+
+    /** @var \Box\Spout\Common\Helper\GlobalFunctionsHelper Helper to work with global functions */
+    protected $globalFunctionsHelper;
+
+    /** @var array Map representing the encodings supporting BOMs (key) and their associated BOM (value) */
+    protected $supportedEncodingsWithBom;
+
+    /**
+     * @param \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($globalFunctionsHelper)
+    {
+        $this->globalFunctionsHelper = $globalFunctionsHelper;
+
+        $this->supportedEncodingsWithBom = [
+            self::ENCODING_UTF8     => self::BOM_UTF8,
+            self::ENCODING_UTF16_LE => self::BOM_UTF16_LE,
+            self::ENCODING_UTF16_BE => self::BOM_UTF16_BE,
+            self::ENCODING_UTF32_LE => self::BOM_UTF32_LE,
+            self::ENCODING_UTF32_BE => self::BOM_UTF32_BE,
+        ];
+    }
+
+    /**
+     * Returns the number of bytes to use as offset in order to skip the BOM.
+     *
+     * @param resource $filePointer Pointer to the file to check
+     * @param string $encoding Encoding of the file to check
+     * @return int Bytes offset to apply to skip the BOM (0 means no BOM)
+     */
+    public function getBytesOffsetToSkipBOM($filePointer, $encoding)
+    {
+        $byteOffsetToSkipBom = 0;
+
+        if ($this->hasBom($filePointer, $encoding)) {
+            $bomUsed = $this->supportedEncodingsWithBom[$encoding];
+
+            // we skip the N first bytes
+            $byteOffsetToSkipBom = strlen($bomUsed);
+        }
+
+        return $byteOffsetToSkipBom;
+    }
+
+    /**
+     * Returns whether the file identified by the given pointer has a BOM.
+     *
+     * @param resource $filePointer Pointer to the file to check
+     * @param string $encoding Encoding of the file to check
+     * @return bool TRUE if the file has a BOM, FALSE otherwise
+     */
+    protected function hasBOM($filePointer, $encoding)
+    {
+        $hasBOM = false;
+
+        $this->globalFunctionsHelper->rewind($filePointer);
+
+        if (array_key_exists($encoding, $this->supportedEncodingsWithBom)) {
+            $potentialBom = $this->supportedEncodingsWithBom[$encoding];
+            $numBytesInBom = strlen($potentialBom);
+
+            $hasBOM = ($this->globalFunctionsHelper->fgets($filePointer, $numBytesInBom + 1) === $potentialBom);
+        }
+
+        return $hasBOM;
+    }
+
+    /**
+     * Attempts to convert a non UTF-8 string into UTF-8.
+     *
+     * @param string $string Non UTF-8 string to be converted
+     * @param string $sourceEncoding The encoding used to encode the source string
+     * @return string The converted, UTF-8 string
+     * @throws \Box\Spout\Common\Exception\EncodingConversionException If conversion is not supported or if the conversion failed
+     */
+    public function attemptConversionToUTF8($string, $sourceEncoding)
+    {
+        return $this->attemptConversion($string, $sourceEncoding, self::ENCODING_UTF8);
+    }
+
+    /**
+     * Attempts to convert a UTF-8 string into the given encoding.
+     *
+     * @param string $string UTF-8 string to be converted
+     * @param string $targetEncoding The encoding the string should be re-encoded into
+     * @return string The converted string, encoded with the given encoding
+     * @throws \Box\Spout\Common\Exception\EncodingConversionException If conversion is not supported or if the conversion failed
+     */
+    public function attemptConversionFromUTF8($string, $targetEncoding)
+    {
+        return $this->attemptConversion($string, self::ENCODING_UTF8, $targetEncoding);
+    }
+
+    /**
+     * Attempts to convert the given string to the given encoding.
+     * Depending on what is installed on the server, we will try to iconv or mbstring.
+     *
+     * @param string $string string to be converted
+     * @param string $sourceEncoding The encoding used to encode the source string
+     * @param string $targetEncoding The encoding the string should be re-encoded into
+     * @return string The converted string, encoded with the given encoding
+     * @throws \Box\Spout\Common\Exception\EncodingConversionException If conversion is not supported or if the conversion failed
+     */
+    protected function attemptConversion($string, $sourceEncoding, $targetEncoding)
+    {
+        // if source and target encodings are the same, it's a no-op
+        if ($sourceEncoding === $targetEncoding) {
+            return $string;
+        }
+
+        $convertedString = null;
+
+        if ($this->canUseIconv()) {
+            $convertedString = $this->globalFunctionsHelper->iconv($string, $sourceEncoding, $targetEncoding);
+        } else if ($this->canUseMbString()) {
+            $convertedString = $this->globalFunctionsHelper->mb_convert_encoding($string, $sourceEncoding, $targetEncoding);
+        } else {
+            throw new EncodingConversionException("The conversion from $sourceEncoding to $targetEncoding is not supported. Please install \"iconv\" or \"PHP Intl\".");
+        }
+
+        if ($convertedString === false) {
+            throw new EncodingConversionException("The conversion from $sourceEncoding to $targetEncoding failed.");
+        }
+
+        return $convertedString;
+    }
+
+    /**
+     * Returns whether "iconv" can be used.
+     *
+     * @return bool TRUE if "iconv" is available and can be used, FALSE otherwise
+     */
+    protected function canUseIconv()
+    {
+        return $this->globalFunctionsHelper->function_exists('iconv');
+    }
+
+    /**
+     * Returns whether "mb_string" functions can be used.
+     * These functions come with the PHP Intl package.
+     *
+     * @return bool TRUE if "mb_string" functions are available and can be used, FALSE otherwise
+     */
+    protected function canUseMbString()
+    {
+        return $this->globalFunctionsHelper->function_exists('mb_convert_encoding');
+    }
+}

src/Spout/Common/Helper/FileSystemHelper.php

@@ -36,11 +36,11 @@ class FileSystemHelper
     {
         $this->throwIfOperationNotInBaseFolder($parentFolderPath);
 
-        $folderPath = $parentFolderPath . DIRECTORY_SEPARATOR . $folderName;
+        $folderPath = $parentFolderPath . '/' . $folderName;
 
         $wasCreationSuccessful = mkdir($folderPath, 0777, true);
         if (!$wasCreationSuccessful) {
-            throw new IOException('Unable to create folder: ' . $folderPath);
+            throw new IOException("Unable to create folder: $folderPath");
         }
 
         return $folderPath;
@@ -60,11 +60,11 @@ class FileSystemHelper
     {
         $this->throwIfOperationNotInBaseFolder($parentFolderPath);
 
-        $filePath = $parentFolderPath . DIRECTORY_SEPARATOR . $fileName;
+        $filePath = $parentFolderPath . '/' . $fileName;
 
         $wasCreationSuccessful = file_put_contents($filePath, $fileContents);
-        if (!$wasCreationSuccessful) {
-            throw new IOException('Unable to create file: ' . $filePath);
+        if ($wasCreationSuccessful === false) {
+            throw new IOException("Unable to create file: $filePath");
         }
 
         return $filePath;
@@ -126,7 +126,7 @@ class FileSystemHelper
     {
         $isInBaseFolder = (strpos($operationFolderPath, $this->baseFolderPath) === 0);
         if (!$isInBaseFolder) {
-            throw new IOException('Cannot perform I/O operation outside of the base folder: ' . $this->baseFolderPath);
+            throw new IOException("Cannot perform I/O operation outside of the base folder: {$this->baseFolderPath}");
         }
     }
 }

src/Spout/Common/Helper/GlobalFunctionsHelper.php

@@ -106,6 +106,19 @@ class GlobalFunctionsHelper
         return fputcsv($handle, $fields, $delimiter, $enclosure);
     }
 
+    /**
+     * Wrapper around global function fwrite()
+     * @see fwrite()
+     *
+     * @param resource $handle
+     * @param string $string
+     * @return int
+     */
+    public function fwrite($handle, $string)
+    {
+        return fwrite($handle, $string);
+    }
+
     /**
      * Wrapper around global function fclose()
      * @see fclose()
@@ -147,13 +160,25 @@ class GlobalFunctionsHelper
      * @see file_get_contents()
      *
      * @param string $filePath
-     * @return bool
+     * @return string
      */
     public function file_get_contents($filePath)
     {
         return file_get_contents($filePath);
     }
 
+    /**
+     * Wrapper around global function feof()
+     * @see feof()
+     *
+     * @param resource
+     * @return bool
+     */
+    public function feof($handle)
+    {
+        return feof($handle);
+    }
+
     /**
      * Wrapper around global function is_readable()
      * @see is_readable()
@@ -190,4 +215,73 @@ class GlobalFunctionsHelper
     {
         header($string);
     }
+
+    /**
+     * Wrapper around global function iconv()
+     * @see iconv()
+     *
+     * @param string $string The string to be converted
+     * @param string $sourceEncoding The encoding of the source string
+     * @param string $targetEncoding The encoding the source string should be converted to
+     * @return string|bool the converted string or FALSE on failure.
+     */
+    public function iconv($string, $sourceEncoding, $targetEncoding)
+    {
+        return iconv($sourceEncoding, $targetEncoding, $string);
+    }
+
+    /**
+     * Wrapper around global function mb_convert_encoding()
+     * @see mb_convert_encoding()
+     *
+     * @param string $string The string to be converted
+     * @param string $sourceEncoding The encoding of the source string
+     * @param string $targetEncoding The encoding the source string should be converted to
+     * @return string|bool the converted string or FALSE on failure.
+     */
+    public function mb_convert_encoding($string, $sourceEncoding, $targetEncoding)
+    {
+        return mb_convert_encoding($string, $targetEncoding, $sourceEncoding);
+    }
+
+    /**
+     * Wrapper around global function stream_get_line()
+     * @see stream_get_line()
+     *
+     * @param resource $handle
+     * @param int $length
+     * @param string|void $ending
+     * @return string|bool
+     */
+    public function stream_get_line($handle, $length, $ending = null)
+    {
+        return stream_get_line($handle, $length, $ending);
+    }
+
+    /**
+     * Wrapper around global function str_getcsv()
+     * @see str_getcsv()
+     *
+     * @param string $input
+     * @param string|void $delimiter
+     * @param string|void $enclosure
+     * @param string|void $escape
+     * @return array
+     */
+    public function str_getcsv($input, $delimiter = null, $enclosure = null, $escape = null)
+    {
+        return str_getcsv($input, $delimiter, $enclosure, $escape);
+    }
+
+    /**
+     * Wrapper around global function function_exists()
+     * @see function_exists()
+     *
+     * @param string $functionName
+     * @return bool
+     */
+    public function function_exists($functionName)
+    {
+        return function_exists($functionName);
+    }
 }

src/Spout/Reader/AbstractReader.php

@@ -4,7 +4,6 @@ namespace Box\Spout\Reader;
 
 use Box\Spout\Common\Exception\IOException;
 use Box\Spout\Reader\Exception\ReaderNotOpenedException;
-use Box\Spout\Reader\Exception\EndOfFileReachedException;
 
 /**
  * Class AbstractReader
@@ -14,18 +13,9 @@ use Box\Spout\Reader\Exception\EndOfFileReachedException;
  */
 abstract class AbstractReader implements ReaderInterface
 {
-    /** @var int Used to keep track of the row index */
-    protected $currentRowIndex = 0;
-
     /** @var bool Indicates whether the stream is currently open */
     protected $isStreamOpened = false;
 
-    /** @var bool Indicates whether all rows have been read */
-    protected $hasReachedEndOfFile = false;
-
-    /** @var array Buffer used to store the row data, while checking if there are more rows to read */
-    protected $rowDataBuffer = null;
-
     /** @var \Box\Spout\Common\Helper\GlobalFunctionsHelper Helper to work with global functions */
     protected $globalFunctionsHelper;
 
@@ -38,11 +28,11 @@ abstract class AbstractReader implements ReaderInterface
     abstract protected function openReader($filePath);
 
     /**
-     * Reads and returns next row if available.
+     * Returns an iterator to iterate over sheets.
      *
-     * @return array|null Array that contains the data for the read row or null at the end of the file
+     * @return \Iterator To iterate over sheets
      */
-    abstract protected function read();
+    abstract public function getConcreteSheetIterator();
 
     /**
      * Closes the reader. To be used after reading the file.
@@ -74,20 +64,17 @@ abstract class AbstractReader implements ReaderInterface
         if (!$this->isPhpStream($filePath)) {
             // we skip the checks if the provided file path points to a PHP stream
             if (!$this->globalFunctionsHelper->file_exists($filePath)) {
-                throw new IOException('Could not open ' . $filePath . ' for reading! File does not exist.');
+                throw new IOException("Could not open $filePath for reading! File does not exist.");
             } else if (!$this->globalFunctionsHelper->is_readable($filePath)) {
-                throw new IOException('Could not open ' . $filePath . ' for reading! File is not readable.');
+                throw new IOException("Could not open $filePath for reading! File is not readable.");
             }
         }
 
-        $this->currentRowIndex = 0;
-        $this->hasReachedEndOfFile = false;
-
         try {
             $this->openReader($filePath);
             $this->isStreamOpened = true;
         } catch (\Exception $exception) {
-            throw new IOException('Could not open ' . $filePath . ' for reading! (' . $exception->getMessage() . ')');
+            throw new IOException("Could not open $filePath for reading! ({$exception->getMessage()})");
         }
     }
 
@@ -103,82 +90,18 @@ abstract class AbstractReader implements ReaderInterface
     }
 
     /**
-     * Returns whether all rows have been read (i.e. if we are at the end of the file).
-     * To know if the end of file has been reached, it uses a buffer. If the buffer is
-     * empty (meaning, nothing has been read or previous read line has been consumed), then
-     * it reads the next line, store it in the buffer for the next time or flip a variable if
-     * the end of file has been reached.
+     * Returns an iterator to iterate over sheets.
      *
-     * @return bool Whether all rows have been read (i.e. if we are at the end of the file)
-     * @throws \Box\Spout\Reader\Exception\ReaderNotOpenedException If the stream was not opened first
+     * @return \Iterator To iterate over sheets
+     * @throws \Box\Spout\Reader\Exception\ReaderNotOpenedException If called before opening the reader
      */
-    public function hasNextRow()
+    public function getSheetIterator()
     {
         if (!$this->isStreamOpened) {
-            throw new ReaderNotOpenedException('Stream should be opened first.');
+            throw new ReaderNotOpenedException('Reader should be opened first.');
         }
 
-        if ($this->hasReachedEndOfFile) {
-            return false;
-        }
-
-        // if the buffer contains unprocessed row
-        if (!$this->isRowDataBufferEmpty()) {
-            return true;
-        }
-
-        // otherwise, try to read the next line line, and store it in the buffer
-        $this->rowDataBuffer = $this->read();
-
-        // if the buffer is still empty after reading a row, it means end of file was reached
-        $this->hasReachedEndOfFile = $this->isRowDataBufferEmpty();
-
-        return (!$this->hasReachedEndOfFile);
-    }
-
-    /**
-     * Returns next row if available. The row is either retrieved from the buffer if it is not empty or fetched by
-     * actually reading the file.
-     *
-     * @return array Array that contains the data for the read row
-     * @throws \Box\Spout\Common\Exception\IOException If the stream was not opened first
-     * @throws \Box\Spout\Reader\Exception\EndOfFileReachedException
-     */
-    public function nextRow()
-    {
-        if (!$this->hasNextRow()) {
-            throw new EndOfFileReachedException('End of file was reached. Cannot read more rows.');
-        }
-
-        // Get data from buffer (if the buffer was empty, it was filled by the call to hasNextRow())
-        $rowData = $this->rowDataBuffer;
-
-        // empty buffer to mark the row as consumed
-        $this->emptyRowDataBuffer();
-
-        $this->currentRowIndex++;
-
-        return $rowData;
-    }
-
-    /**
-     * Returns whether the buffer where the row data is stored is empty
-     *
-     * @return bool
-     */
-    protected function isRowDataBufferEmpty()
-    {
-        return ($this->rowDataBuffer === null);
-    }
-
-    /**
-     * Empty the buffer that stores row data
-     *
-     * @return void
-     */
-    protected function emptyRowDataBuffer()
-    {
-        $this->rowDataBuffer = null;
+        return $this->getConcreteSheetIterator();
     }
 
     /**
@@ -190,6 +113,12 @@ abstract class AbstractReader implements ReaderInterface
     {
         if ($this->isStreamOpened) {
             $this->closeReader();
+
+            $sheetIterator = $this->getConcreteSheetIterator();
+            if ($sheetIterator) {
+                $sheetIterator->end();
+            }
+
             $this->isStreamOpened = false;
         }
     }

src/Spout/Reader/CSV.php

@@ -1,130 +0,0 @@
-<?php
-
-namespace Box\Spout\Reader;
-
-use Box\Spout\Common\Exception\IOException;
-
-/**
- * Class CSV
- * This class provides support to read data from a CSV file.
- *
- * @package Box\Spout\Reader
- */
-class CSV extends AbstractReader
-{
-    const UTF8_BOM = "\xEF\xBB\xBF";
-
-    /** @var resource Pointer to the file to be written */
-    protected $filePointer;
-
-    /** @var string Defines the character used to delimit fields (one character only) */
-    protected $fieldDelimiter = ',';
-
-    /** @var string Defines the character used to enclose fields (one character only) */
-    protected $fieldEnclosure = '"';
-
-    /**
-     * Sets the field delimiter for the CSV
-     *
-     * @param string $fieldDelimiter Character that delimits fields
-     * @return CSV
-     */
-    public function setFieldDelimiter($fieldDelimiter)
-    {
-        $this->fieldDelimiter = $fieldDelimiter;
-        return $this;
-    }
-
-    /**
-     * Sets the field enclosure for the CSV
-     *
-     * @param string $fieldEnclosure Character that enclose fields
-     * @return CSV
-     */
-    public function setFieldEnclosure($fieldEnclosure)
-    {
-        $this->fieldEnclosure = $fieldEnclosure;
-        return $this;
-    }
-
-    /**
-     * Opens the file at the given path to make it ready to be read.
-     * The file must be UTF-8 encoded.
-     * @TODO add encoding detection/conversion
-     *
-     * @param  string $filePath Path of the CSV file to be read
-     * @return void
-     * @throws \Box\Spout\Common\Exception\IOException
-     */
-    protected function openReader($filePath)
-    {
-        $this->filePointer = $this->globalFunctionsHelper->fopen($filePath, 'r');
-        if (!$this->filePointer) {
-            throw new IOException('Could not open file ' . $filePath . ' for reading.');
-        }
-
-        $this->skipUtf8Bom();
-    }
-
-    /**
-     * This skips the UTF-8 BOM if inserted at the beginning of the file
-     * by moving the file pointer after it, so that it is not read.
-     *
-     * @return void
-     */
-    protected function skipUtf8Bom()
-    {
-        $this->globalFunctionsHelper->rewind($this->filePointer);
-
-        $hasUtf8Bom = ($this->globalFunctionsHelper->fgets($this->filePointer, 4) === self::UTF8_BOM);
-
-        if ($hasUtf8Bom) {
-            // we skip the 2 first bytes (so start from the 3rd byte)
-            $this->globalFunctionsHelper->fseek($this->filePointer, 3);
-        } else {
-            // if no BOM, reset the pointer to read from the beginning
-            $this->globalFunctionsHelper->fseek($this->filePointer, 0);
-        }
-    }
-
-    /**
-     * Reads and returns next row if available.
-     * Empty rows are skipped.
-     *
-     * @return array|null Array that contains the data for the read row or null at the end of the file
-     */
-    protected function read()
-    {
-        $lineData = null;
-
-        if ($this->filePointer) {
-            do {
-                $lineData = $this->globalFunctionsHelper->fgetcsv($this->filePointer, 0, $this->fieldDelimiter, $this->fieldEnclosure);
-            } while ($lineData && $this->isEmptyLine($lineData));
-        }
-
-        // When reaching the end of the file, return null instead of false
-        return ($lineData !== false) ? $lineData : null;
-    }
-
-    /**
-     * @param array $lineData Array containing the cells value for the line
-     * @return bool Whether the given line is empty
-     */
-    protected function isEmptyLine($lineData)
-    {
-        return (count($lineData) === 1 && $lineData[0] === null);
-    }
-
-    /**
-     * Closes the reader. To be used after reading the file.
-     *
-     * @return void
-     */
-    protected function closeReader()
-    {
-        if ($this->filePointer) {
-            $this->globalFunctionsHelper->fclose($this->filePointer);
-        }
-    }
-}

src/Spout/Reader/CSV/Reader.php

@@ -0,0 +1,117 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\AbstractReader;
+use Box\Spout\Common\Exception\IOException;
+use Box\Spout\Common\Helper\EncodingHelper;
+
+/**
+ * Class Reader
+ * This class provides support to read data from a CSV file.
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class Reader extends AbstractReader
+{
+    /** @var resource Pointer to the file to be written */
+    protected $filePointer;
+
+    /** @var SheetIterator To iterator over the CSV unique "sheet" */
+    protected $sheetIterator;
+
+    /** @var string Defines the character used to delimit fields (one character only) */
+    protected $fieldDelimiter = ',';
+
+    /** @var string Defines the character used to enclose fields (one character only) */
+    protected $fieldEnclosure = '"';
+
+    /** @var string Encoding of the CSV file to be read */
+    protected $encoding = EncodingHelper::ENCODING_UTF8;
+
+    /**
+     * Sets the field delimiter for the CSV.
+     * Needs to be called before opening the reader.
+     *
+     * @param string $fieldDelimiter Character that delimits fields
+     * @return Reader
+     */
+    public function setFieldDelimiter($fieldDelimiter)
+    {
+        $this->fieldDelimiter = $fieldDelimiter;
+        return $this;
+    }
+
+    /**
+     * Sets the field enclosure for the CSV.
+     * Needs to be called before opening the reader.
+     *
+     * @param string $fieldEnclosure Character that enclose fields
+     * @return Reader
+     */
+    public function setFieldEnclosure($fieldEnclosure)
+    {
+        $this->fieldEnclosure = $fieldEnclosure;
+        return $this;
+    }
+
+    /**
+     * Sets the encoding of the CSV file to be read.
+     * Needs to be called before opening the reader.
+     *
+     * @param string $encoding Encoding of the CSV file to be read
+     * @return Reader
+     */
+    public function setEncoding($encoding)
+    {
+        $this->encoding = $encoding;
+        return $this;
+    }
+
+    /**
+     * Opens the file at the given path to make it ready to be read.
+     * If setEncoding() was not called, it assumes that the file is encoded in UTF-8.
+     *
+     * @param  string $filePath Path of the CSV file to be read
+     * @return void
+     * @throws \Box\Spout\Common\Exception\IOException
+     */
+    protected function openReader($filePath)
+    {
+        $this->filePointer = $this->globalFunctionsHelper->fopen($filePath, 'r');
+        if (!$this->filePointer) {
+            throw new IOException("Could not open file $filePath for reading.");
+        }
+
+        $this->sheetIterator = new SheetIterator(
+            $this->filePointer,
+            $this->fieldDelimiter,
+            $this->fieldEnclosure,
+            $this->encoding,
+            $this->globalFunctionsHelper
+        );
+    }
+
+    /**
+     * Returns an iterator to iterate over sheets.
+     *
+     * @return SheetIterator To iterate over sheets
+     */
+    public function getConcreteSheetIterator()
+    {
+        return $this->sheetIterator;
+    }
+
+
+    /**
+     * Closes the reader. To be used after reading the file.
+     *
+     * @return void
+     */
+    protected function closeReader()
+    {
+        if ($this->filePointer) {
+            $this->globalFunctionsHelper->fclose($this->filePointer);
+        }
+    }
+}

src/Spout/Reader/CSV/RowIterator.php

@@ -0,0 +1,213 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\IteratorInterface;
+use Box\Spout\Common\Helper\EncodingHelper;
+
+/**
+ * Class RowIterator
+ * Iterate over CSV rows.
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class RowIterator implements IteratorInterface
+{
+    /** @var resource Pointer to the CSV file to read */
+    protected $filePointer;
+
+    /** @var int Number of read rows */
+    protected $numReadRows = 0;
+
+    /** @var array|null Buffer used to store the row data, while checking if there are more rows to read */
+    protected $rowDataBuffer = null;
+
+    /** @var bool Indicates whether all rows have been read */
+    protected $hasReachedEndOfFile = false;
+
+    /** @var string Defines the character used to delimit fields (one character only) */
+    protected $fieldDelimiter;
+
+    /** @var string Defines the character used to enclose fields (one character only) */
+    protected $fieldEnclosure;
+
+    /** @var string Encoding of the CSV file to be read */
+    protected $encoding;
+
+    /** @var \Box\Spout\Common\Helper\GlobalFunctionsHelper Helper to work with global functions */
+    protected $globalFunctionsHelper;
+
+    /** @var \Box\Spout\Common\Helper\EncodingHelper Helper to work with different encodings */
+    protected $encodingHelper;
+
+    /** @var string End of line delimiter, encoded using the same encoding as the CSV */
+    protected $encodedEOLDelimiter;
+
+    /**
+     * @param resource $filePointer Pointer to the CSV file to read
+     * @param string $fieldDelimiter Character that delimits fields
+     * @param string $fieldEnclosure Character that enclose fields
+     * @param string $encoding Encoding of the CSV file to be read
+     * @param \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($filePointer, $fieldDelimiter, $fieldEnclosure, $encoding, $globalFunctionsHelper)
+    {
+        $this->filePointer = $filePointer;
+        $this->fieldDelimiter = $fieldDelimiter;
+        $this->fieldEnclosure = $fieldEnclosure;
+        $this->encoding = $encoding;
+        $this->globalFunctionsHelper = $globalFunctionsHelper;
+
+        $this->encodingHelper = new EncodingHelper($globalFunctionsHelper);
+    }
+
+    /**
+     * Rewind the Iterator to the first element
+     * @link http://php.net/manual/en/iterator.rewind.php
+     *
+     * @return void
+     */
+    public function rewind()
+    {
+        $this->rewindAndSkipBom();
+
+        $this->numReadRows = 0;
+        $this->rowDataBuffer = null;
+
+        $this->next();
+    }
+
+    /**
+     * This rewinds and skips the BOM if inserted at the beginning of the file
+     * by moving the file pointer after it, so that it is not read.
+     *
+     * @return void
+     */
+    protected function rewindAndSkipBom()
+    {
+        $byteOffsetToSkipBom = $this->encodingHelper->getBytesOffsetToSkipBOM($this->filePointer, $this->encoding);
+
+        // sets the cursor after the BOM (0 means no BOM, so rewind it)
+        $this->globalFunctionsHelper->fseek($this->filePointer, $byteOffsetToSkipBom);
+    }
+
+    /**
+     * Checks if current position is valid
+     * @link http://php.net/manual/en/iterator.valid.php
+     *
+     * @return boolean
+     */
+    public function valid()
+    {
+        return ($this->filePointer && !$this->hasReachedEndOfFile);
+    }
+
+    /**
+     * Move forward to next element. Empty rows are skipped.
+     * @link http://php.net/manual/en/iterator.next.php
+     *
+     * @return void
+     * @throws \Box\Spout\Common\Exception\EncodingConversionException If unable to convert data to UTF-8
+     */
+    public function next()
+    {
+        $lineData = false;
+        $this->hasReachedEndOfFile = $this->globalFunctionsHelper->feof($this->filePointer);
+
+        if (!$this->hasReachedEndOfFile) {
+            do {
+                $utf8EncodedLineData = $this->getNextUTF8EncodedLine();
+                if ($utf8EncodedLineData !== false) {
+                    $lineData = $this->globalFunctionsHelper->str_getcsv($utf8EncodedLineData, $this->fieldDelimiter, $this->fieldEnclosure);
+                }
+                $hasNowReachedEndOfFile = $this->globalFunctionsHelper->feof($this->filePointer);
+            } while (($lineData === false && !$hasNowReachedEndOfFile) || $this->isEmptyLine($lineData));
+
+            if ($lineData !== false) {
+                $this->rowDataBuffer = $lineData;
+                $this->numReadRows++;
+            } else {
+                // If we reach this point, it means end of file was reached.
+                // This happens when the last lines are empty lines.
+                $this->hasReachedEndOfFile = $hasNowReachedEndOfFile;
+            }
+        }
+    }
+
+    /**
+     * Returns the next line, converted if necessary to UTF-8.
+     * Neither fgets nor fgetcsv don't work with non UTF-8 data... so we need to do some things manually.
+     *
+     * @return string|false The next line for the current file pointer, encoded in UTF-8 or FALSE if nothing to read
+     * @throws \Box\Spout\Common\Exception\EncodingConversionException If unable to convert data to UTF-8
+     */
+    protected function getNextUTF8EncodedLine()
+    {
+        // Read until the EOL delimiter or EOF is reached. The delimiter's encoding needs to match the CSV's encoding.
+        $encodedEOLDelimiter = $this->getEncodedEOLDelimiter();
+        $encodedLineData = $this->globalFunctionsHelper->stream_get_line($this->filePointer, 0, $encodedEOLDelimiter);
+
+        // If the line could have been read, it can be converted to UTF-8
+        $utf8EncodedLineData = ($encodedLineData !== false) ?
+            $this->encodingHelper->attemptConversionToUTF8($encodedLineData, $this->encoding) :
+            false;
+
+        return $utf8EncodedLineData;
+    }
+
+    /**
+     * Returns the end of line delimiter, encoded using the same encoding as the CSV.
+     * The return value is cached.
+     *
+     * @return string
+     */
+    protected function getEncodedEOLDelimiter()
+    {
+        if (!isset($this->encodedEOLDelimiter)) {
+            $this->encodedEOLDelimiter = $this->encodingHelper->attemptConversionFromUTF8("\n", $this->encoding);
+        }
+
+        return $this->encodedEOLDelimiter;
+    }
+
+    /**
+     * @param array $lineData Array containing the cells value for the line
+     * @return bool Whether the given line is empty
+     */
+    protected function isEmptyLine($lineData)
+    {
+        return (is_array($lineData) && count($lineData) === 1 && $lineData[0] === null);
+    }
+
+    /**
+     * Return the current element from the buffer
+     * @link http://php.net/manual/en/iterator.current.php
+     *
+     * @return array|null
+     */
+    public function current()
+    {
+        return $this->rowDataBuffer;
+    }
+
+    /**
+     * Return the key of the current element
+     * @link http://php.net/manual/en/iterator.key.php
+     *
+     * @return int
+     */
+    public function key()
+    {
+        return $this->numReadRows;
+    }
+
+    /**
+     * Cleans up what was created to iterate over the object.
+     *
+     * @return void
+     */
+    public function end()
+    {
+        // do nothing
+    }
+}

src/Spout/Reader/CSV/Sheet.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\SheetInterface;
+
+/**
+ * Class Sheet
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class Sheet implements SheetInterface
+{
+    /** @var RowIterator To iterate over the CSV's rows */
+    protected $rowIterator;
+
+    /**
+     * @param resource $filePointer Pointer to the CSV file to read
+     * @param string $fieldDelimiter Character that delimits fields
+     * @param string $fieldEnclosure Character that enclose fields
+     * @param string $encoding Encoding of the CSV file to be read
+     * @param \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($filePointer, $fieldDelimiter, $fieldEnclosure, $encoding, $globalFunctionsHelper)
+    {
+        $this->rowIterator = new RowIterator($filePointer, $fieldDelimiter, $fieldEnclosure, $encoding, $globalFunctionsHelper);
+    }
+
+    /**
+     * @return RowIterator
+     */
+    public function getRowIterator()
+    {
+        return $this->rowIterator;
+    }
+}

src/Spout/Reader/CSV/SheetIterator.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\IteratorInterface;
+
+/**
+ * Class SheetIterator
+ * Iterate over CSV unique "sheet".
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class SheetIterator implements IteratorInterface
+{
+    /** @var Sheet The CSV unique "sheet" */
+    protected $sheet;
+
+    /** @var bool Whether the unique "sheet" has already been read */
+    protected $hasReadUniqueSheet = false;
+
+    /**
+     * @param resource $filePointer
+     * @param string $fieldDelimiter Character that delimits fields
+     * @param string $fieldEnclosure Character that enclose fields
+     * @param string $encoding Encoding of the CSV file to be read
+     * @param \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($filePointer, $fieldDelimiter, $fieldEnclosure, $encoding, $globalFunctionsHelper)
+    {
+        $this->sheet = new Sheet($filePointer, $fieldDelimiter, $fieldEnclosure, $encoding, $globalFunctionsHelper);
+    }
+
+    /**
+     * Rewind the Iterator to the first element
+     * @link http://php.net/manual/en/iterator.rewind.php
+     *
+     * @return void
+     */
+    public function rewind()
+    {
+        $this->hasReadUniqueSheet = false;
+    }
+
+    /**
+     * Checks if current position is valid
+     * @link http://php.net/manual/en/iterator.valid.php
+     *
+     * @return boolean
+     */
+    public function valid()
+    {
+        return (!$this->hasReadUniqueSheet);
+    }
+
+    /**
+     * Move forward to next element
+     * @link http://php.net/manual/en/iterator.next.php
+     *
+     * @return void
+     */
+    public function next()
+    {
+        $this->hasReadUniqueSheet = true;
+    }
+
+    /**
+     * Return the current element
+     * @link http://php.net/manual/en/iterator.current.php
+     *
+     * @return Sheet
+     */
+    public function current()
+    {
+        return $this->sheet;
+    }
+
+    /**
+     * Return the key of the current element
+     * @link http://php.net/manual/en/iterator.key.php
+     *
+     * @return int
+     */
+    public function key()
+    {
+        return 1;
+    }
+
+    /**
+     * Cleans up what was created to iterate over the object.
+     *
+     * @return void
+     */
+    public function end()
+    {
+        // do nothing
+    }
+}

src/Spout/Reader/Exception/EndOfWorksheetsReachedException.php

@@ -1,12 +0,0 @@
-<?php
-
-namespace Box\Spout\Reader\Exception;
-
-/**
- * Class EndOfWorksheetsReachedException
- *
- * @package Box\Spout\Reader\Exception
- */
-class EndOfWorksheetsReachedException extends ReaderException
-{
-}

src/Spout/Reader/Exception/NoSheetsFoundException.php

@@ -3,10 +3,10 @@
 namespace Box\Spout\Reader\Exception;
 
 /**
- * Class EndOfFileReachedException
+ * Class NoSheetsFoundException
  *
  * @package Box\Spout\Reader\Exception
  */
-class EndOfFileReachedException extends ReaderException
+class NoSheetsFoundException extends ReaderException
 {
 }

src/Spout/Reader/Exception/XMLProcessingException.php

@@ -3,10 +3,10 @@
 namespace Box\Spout\Reader\Exception;
 
 /**
- * Class NoWorksheetsFoundException
+ * Class XMLProcessingException
  *
  * @package Box\Spout\Reader\Exception
  */
-class NoWorksheetsFoundException extends ReaderException
+class XMLProcessingException extends ReaderException
 {
 }

src/Spout/Reader/Helper/XLSX/SharedStringsHelper.php

@@ -1,325 +0,0 @@
-<?php
-
-namespace Box\Spout\Reader\Helper\XLSX;
-
-use Box\Spout\Common\Exception\IOException;
-use Box\Spout\Common\Helper\FileSystemHelper;
-use Box\Spout\Reader\Exception\SharedStringNotFoundException;
-
-/**
- * Class SharedStringsHelper
- * This class provides helper functions for reading sharedStrings XML file
- *
- * @package Box\Spout\Reader\Helper\XLSX
- */
-class SharedStringsHelper
-{
-    /** Path of sharedStrings XML file inside the XLSX file */
-    const SHARED_STRINGS_XML_FILE_PATH = 'xl/sharedStrings.xml';
-
-    /** Main namespace for the sharedStrings.xml file */
-    const MAIN_NAMESPACE_FOR_SHARED_STRINGS_XML = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
-
-    /**
-     * To avoid running out of memory when extracting the shared strings, they will be saved to temporary files
-     * instead of in memory. Then, when accessing a string, the corresponding file contents will be loaded in memory
-     * and the string will be quickly retrieved.
-     * The performance bottleneck is not when creating these temporary files, but rather when loading their content.
-     * Because the contents of the last loaded file stays in memory until another file needs to be loaded, it works
-     * best when the indexes of the shared strings are sorted in the sheet data.
-     * 10,000 was chosen because it creates small files that are fast to be loaded in memory.
-     */
-    const MAX_NUM_STRINGS_PER_TEMP_FILE = 10000;
-
-    /** Value to use to escape the line feed character ("\n") */
-    const ESCAPED_LINE_FEED_CHARACTER = '_x000A_';
-
-    /** @var string Path of the XLSX file being read */
-    protected $filePath;
-
-    /** @var string Temporary folder where the temporary files to store shared strings will be stored */
-    protected $tempFolder;
-
-    /** @var \Box\Spout\Writer\Helper\XLSX\FileSystemHelper Helper to perform file system operations */
-    protected $fileSystemHelper;
-
-    /** @var resource Pointer to the last temp file a shared string was written to */
-    protected $tempFilePointer;
-
-    /**
-     * @var string Path of the temporary file whose contents is currently stored in memory
-     * @see MAX_NUM_STRINGS_PER_TEMP_FILE
-     */
-    protected $inMemoryTempFilePath;
-
-    /**
-     * @var string Contents of the temporary file that was last read
-     * @see MAX_NUM_STRINGS_PER_TEMP_FILE
-     */
-    protected $inMemoryTempFileContents;
-
-    /**
-     * @param string $filePath Path of the XLSX file being read
-     * @param string|void $tempFolder Temporary folder where the temporary files to store shared strings will be stored
-     */
-    public function __construct($filePath, $tempFolder = null)
-    {
-        $this->filePath = $filePath;
-
-        $rootTempFolder = ($tempFolder) ?: sys_get_temp_dir();
-        $this->fileSystemHelper = new FileSystemHelper($rootTempFolder);
-        $this->tempFolder = $this->fileSystemHelper->createFolder($rootTempFolder, uniqid('sharedstrings'));
-    }
-
-    /**
-     * Returns whether the XLSX file contains a shared strings XML file
-     *
-     * @return bool
-     */
-    public function hasSharedStrings()
-    {
-        $hasSharedStrings = false;
-        $zip = new \ZipArchive();
-
-        if ($zip->open($this->filePath) === true) {
-            $hasSharedStrings = ($zip->locateName(self::SHARED_STRINGS_XML_FILE_PATH) !== false);
-            $zip->close();
-        }
-
-        return $hasSharedStrings;
-    }
-
-    /**
-     * Builds an in-memory array containing all the shared strings of the worksheet.
-     * All the strings are stored in a XML file, located at 'xl/sharedStrings.xml'.
-     * It is then accessed by the worksheet data, via the string index in the built table.
-     *
-     * More documentation available here: http://msdn.microsoft.com/en-us/library/office/gg278314.aspx
-     *
-     * The XML file can be really big with worksheets containing a lot of data. That is why
-     * we need to use a XML reader that provides streaming like the XMLReader library.
-     * Please note that SimpleXML does not provide such a functionality but since it is faster
-     * and more handy to parse few XML nodes, it is used in combination with XMLReader for that purpose.
-     *
-     * @return void
-     * @throws \Box\Spout\Common\Exception\IOException If sharedStrings.xml can't be read
-     */
-    public function extractSharedStrings()
-    {
-        $xmlReader = new \XMLReader();
-        $sharedStringIndex = 0;
-        $this->tempFilePointer = null;
-        $escaper = new \Box\Spout\Common\Escaper\XLSX();
-
-        $sharedStringsFilePath = $this->getSharedStringsFilePath();
-        if ($xmlReader->open($sharedStringsFilePath, null, LIBXML_NONET) === false) {
-            throw new IOException('Could not open "' . self::SHARED_STRINGS_XML_FILE_PATH . '".');
-        }
-
-        while ($xmlReader->read() && $xmlReader->name !== 'si') {
-            // do nothing until a 'si' tag is reached
-        }
-
-        while ($xmlReader->name === 'si') {
-            $node = new \SimpleXMLElement($xmlReader->readOuterXml());
-            $node->registerXPathNamespace('ns', self::MAIN_NAMESPACE_FOR_SHARED_STRINGS_XML);
-
-            // removes nodes that should not be read, like the pronunciation of the Kanji characters
-            $cleanNode = $this->removeSuperfluousTextNodes($node);
-
-            // find all text nodes 't'; there can be multiple if the cell contains formatting
-            $textNodes = $cleanNode->xpath('//ns:t');
-
-            $textValue = '';
-            foreach ($textNodes as $textNode) {
-                if ($this->shouldPreserveWhitespace($textNode)) {
-                    $textValue .= $textNode->__toString();
-                } else {
-                    $textValue .= trim($textNode->__toString());
-                }
-            }
-
-            $unescapedTextValue = $escaper->unescape($textValue);
-
-            // The shared string retrieval logic expects each cell data to be on one line only
-            // Encoding the line feed character allows to preserve this assumption
-            $lineFeedEncodedTextValue = $this->escapeLineFeed($unescapedTextValue);
-
-            $this->writeSharedStringToTempFile($lineFeedEncodedTextValue, $sharedStringIndex);
-
-            $sharedStringIndex++;
-
-            // jump to the next 'si' tag
-            $xmlReader->next('si');
-        }
-
-        // close pointer to the last temp file that was written
-        if ($this->tempFilePointer) {
-            fclose($this->tempFilePointer);
-        }
-
-        $xmlReader->close();
-    }
-
-    /**
-     * @return string The path to the shared strings XML file, working cross-platforms
-     */
-    protected function getSharedStringsFilePath()
-    {
-        $sharedStringsXmlFilePath = str_replace('/', DIRECTORY_SEPARATOR, self::SHARED_STRINGS_XML_FILE_PATH);
-        return 'zip://' . $this->filePath . '#' . $sharedStringsXmlFilePath;
-    }
-
-    /**
-     * Removes nodes that should not be read, like the pronunciation of the Kanji characters.
-     * By keeping them, their text content would be added to the read string.
-     *
-     * @param \SimpleXMLElement $parentNode Parent node that may contain nodes to remove
-     * @return \SimpleXMLElement Cleaned parent node
-     */
-    protected function removeSuperfluousTextNodes($parentNode)
-    {
-        $tagsToRemove = [
-            'rPh', // Pronunciation of the text
-        ];
-
-        foreach ($tagsToRemove as $tagToRemove) {
-            $xpath = '//ns:' . $tagToRemove;
-            $nodesToRemove = $parentNode->xpath($xpath);
-
-            foreach ($nodesToRemove as $nodeToRemove) {
-                // This is how to remove a node from the XML
-                unset($nodeToRemove[0]);
-            }
-        }
-
-        return $parentNode;
-    }
-
-    /**
-     * If the text node has the attribute 'xml:space="preserve"', then preserve whitespace.
-     *
-     * @param \SimpleXMLElement $textNode The text node element (<t>) whitespace may be preserved
-     * @return bool Whether whitespace should be preserved
-     */
-    protected function shouldPreserveWhitespace($textNode)
-    {
-        $shouldPreserveWhitespace = false;
-
-        $attributes = $textNode->attributes('xml', true);
-        if ($attributes) {
-            foreach ($attributes as $attributeName => $attributeValue) {
-                if ($attributeName === 'space' && $attributeValue->__toString() === 'preserve') {
-                    $shouldPreserveWhitespace = true;
-                    break;
-                }
-            }
-        }
-
-        return $shouldPreserveWhitespace;
-    }
-
-    /**
-     * Writes the given string to its associated temp file.
-     * A new temporary file is created when the previous one has reached its max capacity.
-     *
-     * @param string $sharedString Shared string to write to the temp file
-     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
-     * @return void
-     */
-    protected function writeSharedStringToTempFile($sharedString, $sharedStringIndex)
-    {
-        $tempFilePath = $this->getSharedStringTempFilePath($sharedStringIndex);
-
-        if (!file_exists($tempFilePath)) {
-            if ($this->tempFilePointer) {
-                fclose($this->tempFilePointer);
-            }
-            $this->tempFilePointer = fopen($tempFilePath, 'w');
-        }
-
-        fwrite($this->tempFilePointer, $sharedString . PHP_EOL);
-    }
-
-    /**
-     * Returns the path for the temp file that should contain the string for the given index
-     *
-     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
-     * @return string The temp file path for the given index
-     */
-    protected function getSharedStringTempFilePath($sharedStringIndex)
-    {
-        $numTempFile = intval($sharedStringIndex / self::MAX_NUM_STRINGS_PER_TEMP_FILE);
-        return $this->tempFolder . DIRECTORY_SEPARATOR . 'sharedstrings' . $numTempFile;
-    }
-
-    /**
-     * Returns the shared string at the given index.
-     * Because the strings have been split into different files, it looks for the value in the correct file.
-     *
-     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
-     * @return string The shared string at the given index
-     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If no shared string found for the given index
-     */
-    public function getStringAtIndex($sharedStringIndex)
-    {
-        $tempFilePath = $this->getSharedStringTempFilePath($sharedStringIndex);
-        $indexInFile = $sharedStringIndex % self::MAX_NUM_STRINGS_PER_TEMP_FILE;
-
-        if (!file_exists($tempFilePath)) {
-            throw new SharedStringNotFoundException("Shared string temp file not found: $tempFilePath ; for index: $sharedStringIndex");
-        }
-
-        if ($this->inMemoryTempFilePath !== $tempFilePath) {
-            // free memory
-            unset($this->inMemoryTempFileContents);
-
-            $this->inMemoryTempFileContents = explode(PHP_EOL, file_get_contents($tempFilePath));
-            $this->inMemoryTempFilePath = $tempFilePath;
-        }
-
-        $sharedString = null;
-        if (array_key_exists($indexInFile, $this->inMemoryTempFileContents)) {
-            $escapedSharedString = $this->inMemoryTempFileContents[$indexInFile];
-            $sharedString = $this->unescapeLineFeed($escapedSharedString);
-        }
-
-        if ($sharedString === null) {
-            throw new SharedStringNotFoundException("Shared string not found for index: $sharedStringIndex");
-        }
-
-        return rtrim($sharedString, PHP_EOL);
-    }
-
-    /**
-     * Escapes the line feed character (\n)
-     *
-     * @param string $unescapedString
-     * @return string
-     */
-    private function escapeLineFeed($unescapedString)
-    {
-        return str_replace("\n", self::ESCAPED_LINE_FEED_CHARACTER, $unescapedString);
-    }
-
-    /**
-     * Unescapes the line feed character (\n)
-     *
-     * @param string $escapedString
-     * @return string
-     */
-    private function unescapeLineFeed($escapedString)
-    {
-        return str_replace(self::ESCAPED_LINE_FEED_CHARACTER, "\n", $escapedString);
-    }
-
-    /**
-     * Deletes the created temporary folder and all its contents
-     *
-     * @return void
-     */
-    public function cleanup()
-    {
-        $this->fileSystemHelper->deleteFolderRecursively($this->tempFolder);
-    }
-}

src/Spout/Reader/Internal/XLSX/Worksheet.php

@@ -1,59 +0,0 @@
-<?php
-
-namespace Box\Spout\Reader\Internal\XLSX;
-
-/**
- * Class Worksheet
- * Represents a worksheet within a XLSX file
- *
- * @package Box\Spout\Reader\Internal\XLSX
- */
-class Worksheet
-{
-    /** @var \Box\Spout\Reader\Sheet The "external" sheet */
-    protected $externalSheet;
-
-    /** @var int Worksheet index, based on the order of appareance in [Content_Types].xml (zero-based) */
-    protected $worksheetIndex;
-
-    /** @var string Path of the XML file containing the worksheet data */
-    protected $dataXmlFilePath;
-
-    /**\
-     * @param \Box\Spout\Reader\Sheet $externalSheet The associated "external" sheet
-     * @param int $worksheetIndex Worksheet index, based on the order of appareance in [Content_Types].xml (zero-based)
-     * @param string $dataXmlFilePath Path of the XML file containing the worksheet data
-     */
-    public function __construct($externalSheet, $worksheetIndex, $dataXmlFilePath)
-    {
-        $this->externalSheet = $externalSheet;
-        $this->worksheetIndex = $worksheetIndex;
-        $this->dataXmlFilePath = $dataXmlFilePath;
-    }
-
-    /**
-     * @return string Path of the XML file containing the worksheet data,
-     *                without the leading slash and working cross-platforms.
-     */
-    public function getDataXmlFilePath()
-    {
-        $dataXmlFilePath = ltrim($this->dataXmlFilePath, '/');
-        return str_replace('/', DIRECTORY_SEPARATOR, $dataXmlFilePath);
-    }
-
-    /**
-     * @return \Box\Spout\Reader\Sheet The "external" sheet
-     */
-    public function getExternalSheet()
-    {
-        return $this->externalSheet;
-    }
-
-    /**
-     * @return int
-     */
-    public function getWorksheetIndex()
-    {
-        return $this->worksheetIndex;
-    }
-}

src/Spout/Reader/IteratorInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Box\Spout\Reader;
+
+/**
+ * Interface IteratorInterface
+ *
+ * @package Box\Spout\Reader
+ */
+interface IteratorInterface extends \Iterator
+{
+    /**
+     * Cleans up what was created to iterate over the object.
+     *
+     * @return void
+     */
+    public function end();
+}

src/Spout/Reader/ReaderFactory.php

@@ -19,7 +19,7 @@ class ReaderFactory
      * 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
-     * @return \Box\Spout\Reader\CSV|\Box\Spout\Reader\XLSX
+     * @return ReaderInterface
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      */
     public static function create($readerType)
@@ -28,10 +28,10 @@ class ReaderFactory
 
         switch ($readerType) {
             case Type::CSV:
-                $reader = new CSV();
+                $reader = new CSV\Reader();
                 break;
             case Type::XLSX:
-                $reader = new XLSX();
+                $reader = new XLSX\Reader();
                 break;
             default:
                 throw new UnsupportedTypeException('No readers supporting the given type: ' . $readerType);

src/Spout/Reader/ReaderInterface.php

@@ -20,26 +20,12 @@ interface ReaderInterface
     public function open($filePath);
 
     /**
-     * Returns whether all rows have been read (i.e. if we are at the end of the file).
-     * To know if the end of file has been reached, it uses a buffer. If the buffer is
-     * empty (meaning, nothing has been read or previous read line has been consumed), then
-     * it reads the next line, store it in the buffer for the next time or flip a variable if
-     * the end of file has been reached.
+     * Returns an iterator to iterate over sheets.
      *
-     * @return bool
-     * @throws \Box\Spout\Common\Exception\IOException If the stream was not opened first
+     * @return \Iterator To iterate over sheets
+     * @throws \Box\Spout\Reader\Exception\ReaderNotOpenedException If called before opening the reader
      */
-    public function hasNextRow();
-
-    /**
-     * Returns next row if available. The row is either retrieved from the buffer if it is not empty or fetched by
-     * actually reading the file.
-     *
-     * @return array Array that contains the data for the read row
-     * @throws \Box\Spout\Common\Exception\IOException If the stream was not opened first
-     * @throws \Box\Spout\Reader\Exception\EndOfFileReachedException
-     */
-    public function nextRow();
+    public function getSheetIterator();
 
     /**
      * Closes the reader, preventing any additional reading

src/Spout/Reader/SheetInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Box\Spout\Reader;
+
+/**
+ * Interface SheetInterface
+ *
+ * @package Box\Spout\Reader
+ */
+interface SheetInterface
+{
+    /**
+     * Returns an iterator to iterate over the sheet's rows.
+     *
+     * @return \Iterator
+     */
+    public function getRowIterator();
+}

src/Spout/Reader/Wrapper/SimpleXMLElement.php

@@ -0,0 +1,161 @@
+<?php
+
+namespace Box\Spout\Reader\Wrapper;
+
+use Box\Spout\Reader\Exception\XMLProcessingException;
+
+
+/**
+ * Class SimpleXMLElement
+ * Wrapper around the built-in SimpleXMLElement. This class does not extend \SimpleXMLElement
+ * because it its constructor is final... Instead, it is used as a passthrough.
+ * @see \SimpleXMLElement
+ *
+ * @package Box\Spout\Reader\Wrapper
+ */
+class SimpleXMLElement
+{
+    use XMLInternalErrorsHelper;
+
+    /** @var \SimpleXMLElement Instance of the wrapped SimpleXMLElement object */
+    protected $simpleXMLElement;
+
+    /**
+     * Creates a new SimpleXMLElement object
+     * @see \SimpleXMLElement::__construct
+     *
+     * @param string $xmlData A well-formed XML string
+     * @throws \Box\Spout\Reader\Exception\XMLProcessingException If the XML string is not well-formed
+     */
+    public function __construct($xmlData)
+    {
+        $this->useXMLInternalErrors();
+
+        try {
+            $this->simpleXMLElement = new \SimpleXMLElement($xmlData);
+        } catch (\Exception $exception) {
+            // if the data is invalid, the constructor will throw an Exception
+            $this->resetXMLInternalErrorsSetting();
+            throw new XMLProcessingException($this->getLastXMLErrorMessage());
+        }
+
+        $this->resetXMLInternalErrorsSetting();
+
+        return $this->simpleXMLElement;
+    }
+
+    /**
+     * Returns the attribute for the given name.
+     *
+     * @param string $name Attribute name
+     * @param string|null|void $namespace An optional namespace for the retrieved attributes
+     * @return string|null The attribute value or NULL if attribute not found
+     */
+    public function getAttribute($name, $namespace = null)
+    {
+        $isPrefix = ($namespace !== null);
+        $attributes = $this->simpleXMLElement->attributes($namespace, $isPrefix);
+        $attributeValue = $attributes->{$name};
+
+        return ($attributeValue !== null) ? (string) $attributeValue : null;
+    }
+
+    /**
+     * Creates a prefix/ns context for the next XPath query
+     * @see \SimpleXMLElement::registerXPathNamespace
+     *
+     * @param string $prefix The namespace prefix to use in the XPath query for the namespace given in "namespace".
+     * @param string $namespace The namespace to use for the XPath query. This must match a namespace in
+     *                          use by the XML document or the XPath query using "prefix" will not return any results.
+     * @return bool TRUE on success or FALSE on failure.
+     */
+    public function registerXPathNamespace($prefix, $namespace)
+    {
+        return $this->simpleXMLElement->registerXPathNamespace($prefix, $namespace);
+    }
+
+    /**
+     * Runs XPath query on XML data
+     * @see \SimpleXMLElement::xpath
+     *
+     * @param string $path An XPath path
+     * @return SimpleXMLElement[]|bool an array of SimpleXMLElement objects or FALSE in case of an error.
+     */
+    public function xpath($path)
+    {
+        $elements = $this->simpleXMLElement->xpath($path);
+
+        if ($elements !== false) {
+            $wrappedElements = [];
+            foreach ($elements as $element) {
+                $wrappedElement = $this->wrapSimpleXMLElement($element);
+
+                if ($wrappedElement !== null) {
+                    $wrappedElements[] = $this->wrapSimpleXMLElement($element);
+                }
+            }
+
+            $elements = $wrappedElements;
+        }
+
+        return $elements;
+    }
+
+    /**
+     * Wraps the given element into an instance of the wrapper
+     *
+     * @param \SimpleXMLElement $element Element to be wrapped
+     * @return SimpleXMLElement|null The wrapped element or NULL if the given element is invalid
+     */
+    protected function wrapSimpleXMLElement(\SimpleXMLElement $element)
+    {
+        $wrappedElement = null;
+        $elementAsXML = $element->asXML();
+
+        if ($elementAsXML !== false) {
+            $wrappedElement = new SimpleXMLElement($elementAsXML);
+        }
+
+        return $wrappedElement;
+    }
+
+    /**
+     * Remove all nodes matching the given XPath query.
+     * It does not map to any \SimpleXMLElement function.
+     *
+     * @param string $path An XPath path
+     * @return void
+     */
+    public function removeNodesMatchingXPath($path)
+    {
+        $nodesToRemove = $this->simpleXMLElement->xpath($path);
+
+        foreach ($nodesToRemove as $nodeToRemove) {
+            unset($nodeToRemove[0]);
+        }
+    }
+
+    /**
+     * Returns the first child matching the given tag name
+     *
+     * @param string $tagName
+     * @return SimpleXMLElement|null The first child matching the tag name or NULL if none found
+     */
+    public function getFirstChildByTagName($tagName)
+    {
+        $doesElementExist = isset($this->simpleXMLElement->{$tagName});
+
+        /** @var \SimpleXMLElement $realElement */
+        $realElement = $this->simpleXMLElement->{$tagName};
+
+        return $doesElementExist ? $this->wrapSimpleXMLElement($realElement) : null;
+    }
+
+    /**
+     * @return string
+     */
+    public function __toString()
+    {
+        return $this->simpleXMLElement->__toString();
+    }
+}

src/Spout/Reader/Wrapper/XMLInternalErrorsHelper.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace Box\Spout\Reader\Wrapper;
+
+use Box\Spout\Reader\Exception\XMLProcessingException;
+
+/**
+ * Trait XMLInternalErrorsHelper
+ *
+ * @package Box\Spout\Reader\Wrapper
+ */
+trait XMLInternalErrorsHelper
+{
+    /** @var bool Stores whether XML errors were initially stored internally - used to reset */
+    protected $initialUseInternalErrorsValue;
+
+    /**
+     * To avoid displaying lots of warning/error messages on screen,
+     * stores errors internally instead.
+     *
+     * @return void
+     */
+    protected function useXMLInternalErrors()
+    {
+        libxml_clear_errors();
+        $this->initialUseInternalErrorsValue = libxml_use_internal_errors(true);
+    }
+
+    /**
+     * Throws an XMLProcessingException if an error occured.
+     * It also always resets the "libxml_use_internal_errors" setting back to its initial value.
+     *
+     * @return void
+     * @throws \Box\Spout\Reader\Exception\XMLProcessingException
+     */
+    protected function resetXMLInternalErrorsSettingAndThrowIfXMLErrorOccured()
+    {
+        if ($this->hasXMLErrorOccured()) {
+            $this->resetXMLInternalErrorsSetting();
+            throw new XMLProcessingException($this->getLastXMLErrorMessage());
+        }
+
+        $this->resetXMLInternalErrorsSetting();
+    }
+
+    /**
+     * Returns whether the a XML error has occured since the last time errors were cleared.
+     *
+     * @return bool TRUE if an error occured, FALSE otherwise
+     */
+    private function hasXMLErrorOccured()
+    {
+        return (libxml_get_last_error() !== false);
+    }
+
+    /**
+     * Returns the error message for the last XML error that occured.
+     * @see libxml_get_last_error
+     *
+     * @return String|null Last XML error message or null if no error
+     */
+    private function getLastXMLErrorMessage()
+    {
+        $errorMessage = null;
+        $error = libxml_get_last_error();
+
+        if ($error !== false) {
+            $errorMessage = trim($error->message);
+        }
+
+        return $errorMessage;
+    }
+
+    /**
+     * @return void
+     */
+    protected function resetXMLInternalErrorsSetting()
+    {
+        libxml_use_internal_errors($this->initialUseInternalErrorsValue);
+    }
+
+}

src/Spout/Reader/Wrapper/XMLReader.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace Box\Spout\Reader\Wrapper;
+
+
+/**
+ * Class XMLReader
+ * Wrapper around the built-in XMLReader
+ * @see \XMLReader
+ *
+ * @package Box\Spout\Reader\Wrapper
+ */
+class XMLReader extends \XMLReader
+{
+    use XMLInternalErrorsHelper;
+
+    /**
+     * Set the URI containing the XML to parse
+     * @see \XMLReader::open
+     *
+     * @param string $URI URI pointing to the document
+   	 * @param string|null|void $encoding The document encoding
+   	 * @param int $options A bitmask of the LIBXML_* constants
+     * @return bool TRUE on success or FALSE on failure
+     */
+    public function open($URI, $encoding = null, $options = 0)
+    {
+        $wasOpenSuccessful = false;
+
+        // HHVM does not check if file exists within zip file
+        // @link https://github.com/facebook/hhvm/issues/5779
+        if ($this->isRunningHHVM() && $this->isZipStream($URI)) {
+            if ($this->fileExistsWithinZip($URI)) {
+                $wasOpenSuccessful = parent::open($URI, $encoding, $options|LIBXML_NONET);
+            }
+        } else {
+            $wasOpenSuccessful = parent::open($URI, $encoding, $options|LIBXML_NONET);
+        }
+
+        return $wasOpenSuccessful;
+    }
+
+    /**
+     * Returns whether the given URI is a zip stream.
+     *
+     * @param string $URI URI pointing to a document
+     * @return bool TRUE if URI is a zip stream, FALSE otherwise
+     */
+    protected function isZipStream($URI)
+    {
+        return (strpos($URI, 'zip://') === 0);
+    }
+
+    /**
+     * Returns whether the current environment is HHVM
+     *
+     * @return bool TRUE if running on HHVM, FALSE otherwise
+     */
+    protected function isRunningHHVM()
+    {
+        return defined('HHVM_VERSION');
+    }
+
+    /**
+     * Returns whether the file at the given location exists
+     *
+     * @param string $zipStreamURI URI of a zip stream, e.g. "zip://file.zip#path/inside.xml"
+     * @return bool TRUE if the file exists, FALSE otherwise
+     */
+    protected function fileExistsWithinZip($zipStreamURI)
+    {
+        $doesFileExists = false;
+
+        $pattern = '/zip:\/\/([^#]+)#(.*)/';
+        if (preg_match($pattern, $zipStreamURI, $matches)) {
+            $zipFilePath = $matches[1];
+            $innerFilePath = $matches[2];
+
+            $zip = new \ZipArchive();
+            if ($zip->open($zipFilePath) === true) {
+                $doesFileExists = ($zip->locateName($innerFilePath) !== false);
+                $zip->close();
+            }
+        }
+
+        return $doesFileExists;
+    }
+
+    /**
+     * Move to next node in document
+     * @see \XMLReader::read
+     *
+     * @return bool TRUE on success or FALSE on failure
+     * @throws \Box\Spout\Reader\Exception\XMLProcessingException If an error/warning occurred
+     */
+    public function read()
+    {
+        $this->useXMLInternalErrors();
+
+        $wasReadSuccessful = parent::read();
+
+        $this->resetXMLInternalErrorsSettingAndThrowIfXMLErrorOccured();
+
+        return $wasReadSuccessful;
+    }
+
+    /**
+     * Move cursor to next node skipping all subtrees
+     * @see \XMLReader::next
+     *
+     * @param string|void $localName The name of the next node to move to
+     * @return bool TRUE on success or FALSE on failure
+     * @throws \Box\Spout\Reader\Exception\XMLProcessingException If an error/warning occurred
+     */
+    public function next($localName = null)
+    {
+        $this->useXMLInternalErrors();
+
+        $wasNextSuccessful = parent::next($localName);
+
+        $this->resetXMLInternalErrorsSettingAndThrowIfXMLErrorOccured();
+
+        return $wasNextSuccessful;
+    }
+}

src/Spout/Reader/XLSX.php

@@ -1,258 +0,0 @@
-<?php
-
-namespace Box\Spout\Reader;
-
-use Box\Spout\Common\Exception\BadUsageException;
-use Box\Spout\Common\Exception\IOException;
-use Box\Spout\Reader\Exception\EndOfWorksheetsReachedException;
-use Box\Spout\Reader\Exception\NoWorksheetsFoundException;
-use Box\Spout\Reader\Exception\ReaderNotOpenedException;
-use Box\Spout\Reader\Helper\XLSX\CellHelper;
-use Box\Spout\Reader\Helper\XLSX\SharedStringsHelper;
-use Box\Spout\Reader\Helper\XLSX\WorksheetHelper;
-
-/**
- * Class XLSX
- * This class provides support to read data from a XLSX file
- *
- * @package Box\Spout\Reader
- */
-class XLSX extends AbstractReader
-{
-    /** @var string Real path of the file to read */
-    protected $filePath;
-
-    /** @var string Temporary folder where the temporary files will be created */
-    protected $tempFolder;
-
-    /** @var \ZipArchive */
-    protected $zip;
-
-    /** @var Helper\XLSX\SharedStringsHelper Helper to work with shared strings */
-    protected $sharedStringsHelper;
-
-    /** @var Helper\XLSX\WorksheetHelper Helper to work with worksheets */
-    protected $worksheetHelper;
-
-    /** @var Internal\XLSX\Worksheet[] The list of worksheets present in the file */
-    protected $worksheets;
-
-    /** @var Internal\XLSX\Worksheet The worksheet being read */
-    protected $currentWorksheet;
-
-    /** @var \XMLReader The XMLReader object that will help read sheets XML data */
-    protected $xmlReader;
-
-    /** @var int The number of columns the worksheet has (0 meaning undefined) */
-    protected $numberOfColumns = 0;
-
-    /**
-     * @param string $tempFolder Temporary folder where the temporary files will be created
-     * @return XLSX
-     */
-    public function setTempFolder($tempFolder)
-    {
-        $this->tempFolder = $tempFolder;
-        return $this;
-    }
-
-    /**
-     * Opens the file at the given file path to make it ready to be read.
-     * It also parses the sharedStrings.xml file to get all the shared strings available in memory
-     * and fetches all the available worksheets.
-     *
-     * @param  string $filePath Path of the file to be read
-     * @return void
-     * @throws \Box\Spout\Common\Exception\IOException If the file at the given path or its content cannot be read
-     * @throws Exception\NoWorksheetsFoundException If there are no worksheets in the file
-     */
-    protected function openReader($filePath)
-    {
-        $this->filePath = $filePath;
-        $this->zip = new \ZipArchive();
-
-        if ($this->zip->open($filePath) === true) {
-            $this->sharedStringsHelper = new SharedStringsHelper($filePath, $this->tempFolder);
-
-            if ($this->sharedStringsHelper->hasSharedStrings()) {
-                // Extracts all the strings from the worksheets for easy access in the future
-                $this->sharedStringsHelper->extractSharedStrings();
-            }
-
-            // Fetch all available worksheets
-            $this->worksheetHelper = new WorksheetHelper($filePath, $this->globalFunctionsHelper);
-            $this->worksheets = $this->worksheetHelper->getWorksheets($filePath);
-
-            if (count($this->worksheets) === 0) {
-                throw new NoWorksheetsFoundException('The file must contain at least one worksheet.');
-            }
-        } else {
-            throw new IOException('Could not open ' . $filePath . ' for reading.');
-        }
-    }
-
-    /**
-     * Returns whether another worksheet exists after the current worksheet.
-     *
-     * @return bool Whether another worksheet exists after the current worksheet.
-     * @throws Exception\ReaderNotOpenedException If the stream was not opened first
-     */
-    public function hasNextSheet()
-    {
-        if (!$this->isStreamOpened) {
-            throw new ReaderNotOpenedException('Stream should be opened first.');
-        }
-
-        return $this->worksheetHelper->hasNextWorksheet($this->currentWorksheet, $this->worksheets);
-    }
-
-    /**
-     * Moves the pointer to the current worksheet.
-     * Moving to another worksheet will stop the reading in the current worksheet.
-     *
-     * @return \Box\Spout\Reader\Sheet The next sheet
-     * @throws Exception\ReaderNotOpenedException If the stream was not opened first
-     * @throws Exception\EndOfWorksheetsReachedException If there is no more worksheets to read
-     */
-    public function nextSheet()
-    {
-        if (!$this->hasNextSheet()) {
-            throw new EndOfWorksheetsReachedException('End of worksheets was reached. Cannot read more worksheets.');
-        }
-
-        if ($this->currentWorksheet === null) {
-            $nextWorksheet = $this->worksheets[0];
-        } else {
-            $currentWorksheetIndex = $this->currentWorksheet->getWorksheetIndex();
-            $nextWorksheet = $this->worksheets[$currentWorksheetIndex + 1];
-        }
-
-        $this->initXmlReaderForWorksheetData($nextWorksheet);
-        $this->currentWorksheet = $nextWorksheet;
-
-        // make sure that we are ready to read more rows
-        $this->hasReachedEndOfFile = false;
-        $this->emptyRowDataBuffer();
-
-        return $this->currentWorksheet->getExternalSheet();
-    }
-
-    /**
-     * Initializes the XMLReader object that reads worksheet data for the given worksheet.
-     * If another worksheet was being read, it closes the reader before reopening it for the new worksheet.
-     * The XMLReader is configured to be safe from billion laughs attack.
-     *
-     * @param Internal\XLSX\Worksheet $worksheet The worksheet to initialize the XMLReader with
-     * @return void
-     * @throws \Box\Spout\Common\Exception\IOException If the worksheet data XML cannot be read
-     */
-    protected function initXmlReaderForWorksheetData($worksheet)
-    {
-        // if changing worksheet and the XMLReader was initialized for the current worksheet
-        if ($worksheet != $this->currentWorksheet && $this->xmlReader) {
-            $this->xmlReader->close();
-        } else if (!$this->xmlReader) {
-            $this->xmlReader = new \XMLReader();
-        }
-
-        $worksheetDataXMLFilePath = $worksheet->getDataXmlFilePath();
-
-        $worksheetDataFilePath = 'zip://' . $this->filePath . '#' . $worksheetDataXMLFilePath;
-        if ($this->xmlReader->open($worksheetDataFilePath, null, LIBXML_NONET) === false) {
-            throw new IOException('Could not open "' . $worksheetDataXMLFilePath . '".');
-        }
-    }
-
-    /**
-     * Reads and returns data of the line that comes after the last read line, on the current worksheet.
-     * Empty rows will be skipped.
-     *
-     * @return array|null Array that contains the data for the read line or null at the end of the file
-     * @throws \Box\Spout\Common\Exception\BadUsageException If the pointer to the current worksheet has not been set
-     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If a shared string was not found
-     */
-    protected function read()
-    {
-        if (!$this->currentWorksheet) {
-            throw new BadUsageException('You must call nextSheet() before calling hasNextRow() or nextRow()');
-        }
-
-        $isInsideRowTag = false;
-        $rowData = [];
-
-        while ($this->xmlReader->read()) {
-            if ($this->xmlReader->nodeType == \XMLReader::ELEMENT && $this->xmlReader->name === 'dimension') {
-                // Read dimensions of the worksheet
-                $dimensionRef = $this->xmlReader->getAttribute('ref'); // returns 'A1:M13' for instance (or 'A1' for empty sheet)
-                if (preg_match('/[A-Z\d]+:([A-Z\d]+)/', $dimensionRef, $matches)) {
-                    $lastCellIndex = $matches[1];
-                    $this->numberOfColumns = CellHelper::getColumnIndexFromCellIndex($lastCellIndex) + 1;
-                }
-            } else if ($this->xmlReader->nodeType == \XMLReader::ELEMENT && $this->xmlReader->name === 'row') {
-                // Start of the row description
-                $isInsideRowTag = true;
-
-                // Read spans info if present
-                $numberOfColumnsForRow = $this->numberOfColumns;
-                $spans = $this->xmlReader->getAttribute('spans'); // returns '1:5' for instance
-                if ($spans) {
-                    list(, $numberOfColumnsForRow) = explode(':', $spans);
-                    $numberOfColumnsForRow = intval($numberOfColumnsForRow);
-                }
-                $rowData = ($numberOfColumnsForRow !== 0) ? array_fill(0, $numberOfColumnsForRow, '') : [];
-            } else if ($isInsideRowTag && $this->xmlReader->nodeType == \XMLReader::ELEMENT && $this->xmlReader->name === 'c') {
-                // Start of a cell description
-                $currentCellIndex = $this->xmlReader->getAttribute('r');
-                $currentColumnIndex = CellHelper::getColumnIndexFromCellIndex($currentCellIndex);
-                $node = $this->xmlReader->expand();
-
-                $hasInlineString = ($this->xmlReader->getAttribute('t') === 'inlineStr');
-                $hasSharedString = ($this->xmlReader->getAttribute('t') === 's');
-
-                if ($hasInlineString) {
-                    // inline strings are formatted this way:
-                    // <c r="A1" t="inlineStr"><is><t>[INLINE_STRING]</t></is></c>
-                    $tNode = $node->getElementsByTagName('t')->item(0);
-                    $rowData[$currentColumnIndex] = trim($tNode->nodeValue);
-                } else if ($hasSharedString) {
-                    // shared strings are formatted this way:
-                    // <c r="A1" t="s"><v>[SHARED_STRING_INDEX]</v></c>
-                    $vNode = $node->getElementsByTagName('v')->item(0);
-                    $sharedStringIndex = intval($vNode->nodeValue);
-                    $rowData[$currentColumnIndex] = $this->sharedStringsHelper->getStringAtIndex($sharedStringIndex);
-                } else {
-                    // other values are formatted this way:
-                    // <c r="A1"><v>[VALUE]</v></c>
-                    $vNode = $node->getElementsByTagName('v')->item(0);
-                    $rowData[$currentColumnIndex] = intval($vNode->nodeValue);
-                }
-            } else if ($this->xmlReader->nodeType == \XMLReader::END_ELEMENT && $this->xmlReader->name === 'row') {
-                // End of the row description
-                // If needed, we fill the empty cells
-                $rowData = ($this->numberOfColumns !== 0) ? $rowData : CellHelper::fillMissingArrayIndexes($rowData);
-                break;
-            }
-        }
-
-        // no data means "end of file"
-        return ($rowData !== []) ? $rowData : null;
-    }
-
-    /**
-     * Closes the reader. To be used after reading the file.
-     *
-     * @return void
-     */
-    protected function closeReader()
-    {
-        if ($this->xmlReader) {
-            $this->xmlReader->close();
-        }
-
-        if ($this->zip) {
-            $this->zip->close();
-        }
-
-        $this->sharedStringsHelper->cleanup();
-    }
-}

src/Spout/Reader/XLSX/Helper/CellHelper.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Box\Spout\Reader\Helper\XLSX;
+namespace Box\Spout\Reader\XLSX\Helper;
 
 use Box\Spout\Common\Exception\InvalidArgumentException;
 
@@ -8,7 +8,7 @@ use Box\Spout\Common\Exception\InvalidArgumentException;
  * Class CellHelper
  * This class provides helper functions when working with cells
  *
- * @package Box\Spout\Reader\Helper\XLSX
+ * @package Box\Spout\Reader\XLSX\Helper
  */
 class CellHelper
 {

src/Spout/Reader/XLSX/Helper/SharedStringsCaching/CachingStrategyFactory.php

@@ -0,0 +1,154 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper\SharedStringsCaching;
+
+/**
+ * Class CachingStrategyFactory
+ *
+ * @package Box\Spout\Reader\XLSX\Helper\SharedStringsCaching
+ */
+class CachingStrategyFactory
+{
+    /**
+     * The memory amount needed to store a string was obtained empirically from this data:
+     *
+     *        ------------------------------------
+     *        | Number of chars⁺ | Memory needed |
+     *        ------------------------------------
+     *        |           3,000  |         1 MB  |
+     *        |          15,000  |         2 MB  |
+     *        |          30,000  |         5 MB  |
+     *        |          75,000  |        11 MB  |
+     *        |         150,000  |        21 MB  |
+     *        |         300,000  |        43 MB  |
+     *        |         750,000  |       105 MB  |
+     *        |       1,500,000  |       210 MB  |
+     *        |       2,250,000  |       315 MB  |
+     *        |       3,000,000  |       420 MB  |
+     *        |       4,500,000  |       630 MB  |
+     *        ------------------------------------
+     *
+     *        ⁺ All characters were 1 byte long
+     *
+     * This gives a linear graph where each 1-byte character requires about 150 bytes to be stored.
+     * Given that some characters can take up to 4 bytes, we need 600 bytes per character to be safe.
+     * Also, there is on average about 20 characters per cell (this is entirely empirical data...).
+     *
+     * This means that in order to store one shared string in memory, the memory amount needed is:
+     *   => 20 * 600 ≈ 12KB
+     */
+    const AMOUNT_MEMORY_NEEDED_PER_STRING_IN_KB = 12;
+
+    /**
+     * To avoid running out of memory when extracting a huge number of shared strings, they can be saved to temporary files
+     * instead of in memory. Then, when accessing a string, the corresponding file contents will be loaded in memory
+     * and the string will be quickly retrieved.
+     * The performance bottleneck is not when creating these temporary files, but rather when loading their content.
+     * Because the contents of the last loaded file stays in memory until another file needs to be loaded, it works
+     * best when the indexes of the shared strings are sorted in the sheet data.
+     * 10,000 was chosen because it creates small files that are fast to be loaded in memory.
+     */
+    const MAX_NUM_STRINGS_PER_TEMP_FILE = 10000;
+
+    /** @var CachingStrategyFactory|null Singleton instance */
+    protected static $instance = null;
+
+    /**
+     * Private constructor for singleton
+     */
+    private function __construct()
+    {
+    }
+
+    /**
+     * Returns the singleton instance of the factory
+     *
+     * @return CachingStrategyFactory
+     */
+    public static function getInstance()
+    {
+        if (self::$instance === null) {
+            self::$instance = new CachingStrategyFactory();
+        }
+
+        return self::$instance;
+    }
+
+    /**
+     * Returns the best caching strategy, given the number of unique shared strings
+     * and the amount of memory available.
+     *
+     * @param int $sharedStringsUniqueCount Number of unique shared strings
+     * @param string|void $tempFolder Temporary folder where the temporary files to store shared strings will be stored
+     * @return CachingStrategyInterface The best caching strategy
+     */
+    public function getBestCachingStrategy($sharedStringsUniqueCount, $tempFolder = null)
+    {
+        if ($this->isInMemoryStrategyUsageSafe($sharedStringsUniqueCount)) {
+            return new InMemoryStrategy($sharedStringsUniqueCount);
+        } else {
+            return new FileBasedStrategy($tempFolder, self::MAX_NUM_STRINGS_PER_TEMP_FILE);
+        }
+    }
+
+    /**
+     * Returns whether it is safe to use in-memory caching, given the number of unique shared strings
+     * and the amount of memory available.
+     *
+     * @param int $sharedStringsUniqueCount Number of unique shared strings
+     * @return bool
+     */
+    protected function isInMemoryStrategyUsageSafe($sharedStringsUniqueCount)
+    {
+        $memoryAvailable = $this->getMemoryLimitInKB();
+
+        if ($memoryAvailable === -1) {
+            // if cannot get memory limit or if memory limit set as unlimited, don't trust and play safe
+            return ($sharedStringsUniqueCount < self::MAX_NUM_STRINGS_PER_TEMP_FILE);
+        } else {
+            $memoryNeeded = $sharedStringsUniqueCount * self::AMOUNT_MEMORY_NEEDED_PER_STRING_IN_KB;
+            return ($memoryAvailable > $memoryNeeded);
+        }
+    }
+
+    /**
+     * Returns the PHP "memory_limit" in Kilobytes
+     *
+     * @return float
+     */
+    protected function getMemoryLimitInKB()
+    {
+        $memoryLimitFormatted = $this->getMemoryLimitFromIni();
+        $memoryLimitFormatted = strtolower(trim($memoryLimitFormatted));
+
+        // No memory limit
+        if ($memoryLimitFormatted === '-1') {
+            return -1;
+        }
+
+        if (preg_match('/(\d+)([bkmgt])b?/', $memoryLimitFormatted, $matches)) {
+            $amount = intval($matches[1]);
+            $unit = $matches[2];
+
+            switch ($unit) {
+                case 'b': return ($amount / 1024);
+                case 'k': return $amount;
+                case 'm': return ($amount * 1024);
+                case 'g': return ($amount * 1024 * 1024);
+                case 't': return ($amount * 1024 * 1024 * 1024);
+            }
+        }
+
+        return -1;
+    }
+
+    /**
+     * Returns the formatted "memory_limit" value
+     *
+     * @return string
+     */
+    protected function getMemoryLimitFromIni()
+    {
+        return ini_get('memory_limit');
+    }
+}

src/Spout/Reader/XLSX/Helper/SharedStringsCaching/CachingStrategyInterface.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper\SharedStringsCaching;
+
+/**
+ * Interface CachingStrategyInterface
+ *
+ * @package Box\Spout\Reader\XLSX\Helper\SharedStringsCaching
+ */
+interface CachingStrategyInterface
+{
+    /**
+     * Adds the given string to the cache.
+     *
+     * @param string $sharedString The string to be added to the cache
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return void
+     */
+    public function addStringForIndex($sharedString, $sharedStringIndex);
+
+    /**
+     * Closes the cache after the last shared string was added.
+     * This prevents any additional string from being added to the cache.
+     *
+     * @return void
+     */
+    public function closeCache();
+
+    /**
+     * Returns the string located at the given index from the cache.
+     *
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return string The shared string at the given index
+     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If no shared string found for the given index
+     */
+    public function getStringAtIndex($sharedStringIndex);
+
+    /**
+     * Destroys the cache, freeing memory and removing any created artifacts
+     *
+     * @return void
+     */
+    public function clearCache();
+}

src/Spout/Reader/XLSX/Helper/SharedStringsCaching/FileBasedStrategy.php

@@ -0,0 +1,191 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper\SharedStringsCaching;
+
+use Box\Spout\Common\Helper\FileSystemHelper;
+use Box\Spout\Common\Helper\GlobalFunctionsHelper;
+use Box\Spout\Reader\Exception\SharedStringNotFoundException;
+
+/**
+ * Class FileBasedStrategy
+ *
+ * This class implements the file-based caching strategy for shared strings.
+ * Shared strings are stored in small files (with a max number of strings per file).
+ * This strategy is slower than an in-memory strategy but is used to avoid out of memory crashes.
+ *
+ * @package Box\Spout\Reader\XLSX\Helper\SharedStringsCaching
+ */
+class FileBasedStrategy implements CachingStrategyInterface
+{
+    /** Value to use to escape the line feed character ("\n") */
+    const ESCAPED_LINE_FEED_CHARACTER = '_x000A_';
+
+    /** @var \Box\Spout\Common\Helper\GlobalFunctionsHelper Helper to work with global functions */
+    protected $globalFunctionsHelper;
+
+    /** @var \Box\Spout\Common\Helper\FileSystemHelper Helper to perform file system operations */
+    protected $fileSystemHelper;
+
+    /** @var string Temporary folder where the temporary files will be created */
+    protected $tempFolder;
+
+    /**
+     * @var int Maximum number of strings that can be stored in one temp file
+     * @see CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE
+     */
+    protected $maxNumStringsPerTempFile;
+
+    /** @var resource Pointer to the last temp file a shared string was written to */
+    protected $tempFilePointer;
+
+    /**
+     * @var string Path of the temporary file whose contents is currently stored in memory
+     * @see CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE
+     */
+    protected $inMemoryTempFilePath;
+
+    /**
+     * @var array Contents of the temporary file that was last read
+     * @see CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE
+     */
+    protected $inMemoryTempFileContents;
+
+    /**
+     * @param string|null $tempFolder Temporary folder where the temporary files to store shared strings will be stored
+     * @param int $maxNumStringsPerTempFile Maximum number of strings that can be stored in one temp file
+     */
+    public function __construct($tempFolder, $maxNumStringsPerTempFile)
+    {
+        $rootTempFolder = ($tempFolder) ?: sys_get_temp_dir();
+        $this->fileSystemHelper = new FileSystemHelper($rootTempFolder);
+        $this->tempFolder = $this->fileSystemHelper->createFolder($rootTempFolder, uniqid('sharedstrings'));
+
+        $this->maxNumStringsPerTempFile = $maxNumStringsPerTempFile;
+
+        $this->globalFunctionsHelper = new GlobalFunctionsHelper();
+        $this->tempFilePointer = null;
+    }
+
+    /**
+     * Adds the given string to the cache.
+     *
+     * @param string $sharedString The string to be added to the cache
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return void
+     */
+    public function addStringForIndex($sharedString, $sharedStringIndex)
+    {
+        $tempFilePath = $this->getSharedStringTempFilePath($sharedStringIndex);
+
+        if (!$this->globalFunctionsHelper->file_exists($tempFilePath)) {
+            if ($this->tempFilePointer) {
+                $this->globalFunctionsHelper->fclose($this->tempFilePointer);
+            }
+            $this->tempFilePointer = $this->globalFunctionsHelper->fopen($tempFilePath, 'w');
+        }
+
+        // The shared string retrieval logic expects each cell data to be on one line only
+        // Encoding the line feed character allows to preserve this assumption
+        $lineFeedEncodedSharedString = $this->escapeLineFeed($sharedString);
+
+        $this->globalFunctionsHelper->fwrite($this->tempFilePointer, $lineFeedEncodedSharedString . PHP_EOL);
+    }
+
+    /**
+     * Returns the path for the temp file that should contain the string for the given index
+     *
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return string The temp file path for the given index
+     */
+    protected function getSharedStringTempFilePath($sharedStringIndex)
+    {
+        $numTempFile = intval($sharedStringIndex / $this->maxNumStringsPerTempFile);
+        return $this->tempFolder . '/sharedstrings' . $numTempFile;
+    }
+
+    /**
+     * Closes the cache after the last shared string was added.
+     * This prevents any additional string from being added to the cache.
+     *
+     * @return void
+     */
+    public function closeCache()
+    {
+        // close pointer to the last temp file that was written
+        if ($this->tempFilePointer) {
+            $this->globalFunctionsHelper->fclose($this->tempFilePointer);
+        }
+    }
+
+
+    /**
+     * Returns the string located at the given index from the cache.
+     *
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return string The shared string at the given index
+     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If no shared string found for the given index
+     */
+    public function getStringAtIndex($sharedStringIndex)
+    {
+        $tempFilePath = $this->getSharedStringTempFilePath($sharedStringIndex);
+        $indexInFile = $sharedStringIndex % $this->maxNumStringsPerTempFile;
+
+        if (!$this->globalFunctionsHelper->file_exists($tempFilePath)) {
+            throw new SharedStringNotFoundException("Shared string temp file not found: $tempFilePath ; for index: $sharedStringIndex");
+        }
+
+        if ($this->inMemoryTempFilePath !== $tempFilePath) {
+            // free memory
+            unset($this->inMemoryTempFileContents);
+
+            $this->inMemoryTempFileContents = explode(PHP_EOL, $this->globalFunctionsHelper->file_get_contents($tempFilePath));
+            $this->inMemoryTempFilePath = $tempFilePath;
+        }
+
+        $sharedString = null;
+        if (array_key_exists($indexInFile, $this->inMemoryTempFileContents)) {
+            $escapedSharedString = $this->inMemoryTempFileContents[$indexInFile];
+            $sharedString = $this->unescapeLineFeed($escapedSharedString);
+        }
+
+        if ($sharedString === null) {
+            throw new SharedStringNotFoundException("Shared string not found for index: $sharedStringIndex");
+        }
+
+        return rtrim($sharedString, PHP_EOL);
+    }
+
+    /**
+     * Escapes the line feed characters (\n)
+     *
+     * @param string $unescapedString
+     * @return string
+     */
+    private function escapeLineFeed($unescapedString)
+    {
+        return str_replace("\n", self::ESCAPED_LINE_FEED_CHARACTER, $unescapedString);
+    }
+
+    /**
+     * Unescapes the line feed characters (\n)
+     *
+     * @param string $escapedString
+     * @return string
+     */
+    private function unescapeLineFeed($escapedString)
+    {
+        return str_replace(self::ESCAPED_LINE_FEED_CHARACTER, "\n", $escapedString);
+    }
+
+    /**
+     * Destroys the cache, freeing memory and removing any created artifacts
+     *
+     * @return void
+     */
+    public function clearCache()
+    {
+        if ($this->tempFolder) {
+            $this->fileSystemHelper->deleteFolderRecursively($this->tempFolder);
+        }
+    }
+}

src/Spout/Reader/XLSX/Helper/SharedStringsCaching/InMemoryStrategy.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper\SharedStringsCaching;
+
+use Box\Spout\Reader\Exception\SharedStringNotFoundException;
+
+/**
+ * Class InMemoryStrategy
+ *
+ * This class implements the in-memory caching strategy for shared strings.
+ * This strategy is used when the number of unique strings is low, compared to the memory available.
+ *
+ * @package Box\Spout\Reader\XLSX\Helper\SharedStringsCaching
+ */
+class InMemoryStrategy implements CachingStrategyInterface
+{
+    /** @var \SplFixedArray Array used to cache the shared strings */
+    protected $inMemoryCache;
+
+    /** @var bool Whether the cache has been closed */
+    protected $isCacheClosed;
+
+    /**
+     * @param int $sharedStringsUniqueCount Number of unique shared strings
+     */
+    public function __construct($sharedStringsUniqueCount)
+    {
+        $this->inMemoryCache = new \SplFixedArray($sharedStringsUniqueCount);
+        $this->isCacheClosed = false;
+    }
+
+    /**
+     * Adds the given string to the cache.
+     *
+     * @param string $sharedString The string to be added to the cache
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return void
+     */
+    public function addStringForIndex($sharedString, $sharedStringIndex)
+    {
+        if (!$this->isCacheClosed) {
+            $this->inMemoryCache->offsetSet($sharedStringIndex, $sharedString);
+        }
+    }
+
+    /**
+     * Closes the cache after the last shared string was added.
+     * This prevents any additional string from being added to the cache.
+     *
+     * @return void
+     */
+    public function closeCache()
+    {
+        $this->isCacheClosed = true;
+    }
+
+    /**
+     * Returns the string located at the given index from the cache.
+     *
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return string The shared string at the given index
+     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If no shared string found for the given index
+     */
+    public function getStringAtIndex($sharedStringIndex)
+    {
+        try {
+            return $this->inMemoryCache->offsetGet($sharedStringIndex);
+        } catch (\RuntimeException $e) {
+            throw new SharedStringNotFoundException("Shared string not found for index: $sharedStringIndex");
+        }
+    }
+
+    /**
+     * Destroys the cache, freeing memory and removing any created artifacts
+     *
+     * @return void
+     */
+    public function clearCache()
+    {
+        unset($this->inMemoryCache);
+        $this->isCacheClosed = false;
+    }
+}

src/Spout/Reader/XLSX/Helper/SharedStringsHelper.php

@@ -0,0 +1,249 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper;
+
+use Box\Spout\Common\Exception\IOException;
+use Box\Spout\Reader\Exception\XMLProcessingException;
+use Box\Spout\Reader\Wrapper\SimpleXMLElement;
+use Box\Spout\Reader\Wrapper\XMLReader;
+use Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\CachingStrategyFactory;
+use Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\CachingStrategyInterface;
+
+/**
+ * Class SharedStringsHelper
+ * This class provides helper functions for reading sharedStrings XML file
+ *
+ * @package Box\Spout\Reader\XLSX\Helper
+ */
+class SharedStringsHelper
+{
+    /** Path of sharedStrings XML file inside the XLSX file */
+    const SHARED_STRINGS_XML_FILE_PATH = 'xl/sharedStrings.xml';
+
+    /** Main namespace for the sharedStrings.xml file */
+    const MAIN_NAMESPACE_FOR_SHARED_STRINGS_XML = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
+
+    /** @var string Path of the XLSX file being read */
+    protected $filePath;
+
+    /** @var string Temporary folder where the temporary files to store shared strings will be stored */
+    protected $tempFolder;
+
+    /** @var CachingStrategyInterface The best caching strategy for storing shared strings */
+    protected $cachingStrategy;
+
+    /**
+     * @param string $filePath Path of the XLSX file being read
+     * @param string|void $tempFolder Temporary folder where the temporary files to store shared strings will be stored
+     */
+    public function __construct($filePath, $tempFolder = null)
+    {
+        $this->filePath = $filePath;
+        $this->tempFolder = $tempFolder;
+    }
+
+    /**
+     * Returns whether the XLSX file contains a shared strings XML file
+     *
+     * @return bool
+     */
+    public function hasSharedStrings()
+    {
+        $hasSharedStrings = false;
+        $zip = new \ZipArchive();
+
+        if ($zip->open($this->filePath) === true) {
+            $hasSharedStrings = ($zip->locateName(self::SHARED_STRINGS_XML_FILE_PATH) !== false);
+            $zip->close();
+        }
+
+        return $hasSharedStrings;
+    }
+
+    /**
+     * Builds an in-memory array containing all the shared strings of the sheet.
+     * All the strings are stored in a XML file, located at 'xl/sharedStrings.xml'.
+     * It is then accessed by the sheet data, via the string index in the built table.
+     *
+     * More documentation available here: http://msdn.microsoft.com/en-us/library/office/gg278314.aspx
+     *
+     * The XML file can be really big with sheets containing a lot of data. That is why
+     * we need to use a XML reader that provides streaming like the XMLReader library.
+     * Please note that SimpleXML does not provide such a functionality but since it is faster
+     * and more handy to parse few XML nodes, it is used in combination with XMLReader for that purpose.
+     *
+     * @return void
+     * @throws \Box\Spout\Common\Exception\IOException If sharedStrings.xml can't be read
+     */
+    public function extractSharedStrings()
+    {
+        $xmlReader = new XMLReader();
+        $sharedStringIndex = 0;
+        $escaper = new \Box\Spout\Common\Escaper\XLSX();
+
+        $sharedStringsFilePath = $this->getSharedStringsFilePath();
+        if ($xmlReader->open($sharedStringsFilePath, null, LIBXML_NONET) === false) {
+            throw new IOException('Could not open "' . self::SHARED_STRINGS_XML_FILE_PATH . '".');
+        }
+
+        try {
+            $sharedStringsUniqueCount = $this->getSharedStringsUniqueCount($xmlReader);
+            $this->cachingStrategy = $this->getBestSharedStringsCachingStrategy($sharedStringsUniqueCount);
+
+            while ($xmlReader->read() && $xmlReader->name !== 'si') {
+                // do nothing until a 'si' tag is reached
+            }
+
+            while ($xmlReader->name === 'si') {
+                $node = $this->getSimpleXmlElementNodeFromXMLReader($xmlReader);
+                $node->registerXPathNamespace('ns', self::MAIN_NAMESPACE_FOR_SHARED_STRINGS_XML);
+
+                // removes nodes that should not be read, like the pronunciation of the Kanji characters
+                $cleanNode = $this->removeSuperfluousTextNodes($node);
+
+                // find all text nodes 't'; there can be multiple if the cell contains formatting
+                $textNodes = $cleanNode->xpath('//ns:t');
+
+                $textValue = '';
+                foreach ($textNodes as $textNode) {
+                    if ($this->shouldPreserveWhitespace($textNode)) {
+                        $textValue .= $textNode->__toString();
+                    } else {
+                        $textValue .= trim($textNode->__toString());
+                    }
+                }
+
+                $unescapedTextValue = $escaper->unescape($textValue);
+                $this->cachingStrategy->addStringForIndex($unescapedTextValue, $sharedStringIndex);
+
+                $sharedStringIndex++;
+
+                // jump to the next 'si' tag
+                $xmlReader->next('si');
+            }
+
+        } catch (XMLProcessingException $exception) {
+            throw new IOException("The sharedStrings.xml file is invalid and cannot be read. [{$exception->getMessage()}]");
+        }
+
+        $this->cachingStrategy->closeCache();
+
+        $xmlReader->close();
+    }
+
+    /**
+     * @return string The path to the shared strings XML file
+     */
+    protected function getSharedStringsFilePath()
+    {
+        return 'zip://' . $this->filePath . '#' . self::SHARED_STRINGS_XML_FILE_PATH;
+    }
+
+    /**
+     * Returns the shared strings unique count, as specified in <sst> tag.
+     *
+     * @param \Box\Spout\Reader\Wrapper\XMLReader $xmlReader XMLReader instance
+     * @return int Number of unique shared strings in the sharedStrings.xml file
+     * @throws \Box\Spout\Common\Exception\IOException If sharedStrings.xml is invalid and can't be read
+     */
+    protected function getSharedStringsUniqueCount($xmlReader)
+    {
+        $xmlReader->next('sst');
+
+        // Iterate over the "sst" elements to get the actual "sst ELEMENT" (skips any DOCTYPE)
+        while ($xmlReader->name === 'sst' && $xmlReader->nodeType !== XMLReader::ELEMENT) {
+            $xmlReader->read();
+        }
+
+        return intval($xmlReader->getAttribute('uniqueCount'));
+    }
+
+    /**
+     * Returns the best shared strings caching strategy.
+     *
+     * @param int $sharedStringsUniqueCount
+     * @return CachingStrategyInterface
+     */
+    protected function getBestSharedStringsCachingStrategy($sharedStringsUniqueCount)
+    {
+        return CachingStrategyFactory::getInstance()
+                ->getBestCachingStrategy($sharedStringsUniqueCount, $this->tempFolder);
+    }
+
+    /**
+     * Returns a SimpleXMLElement node from the current node in the given XMLReader instance.
+     * This is to simplify the parsing of the subtree.
+     *
+     * @param \Box\Spout\Reader\Wrapper\XMLReader $xmlReader
+     * @return \Box\Spout\Reader\Wrapper\SimpleXMLElement
+     * @throws \Box\Spout\Common\Exception\IOException If the current node cannot be read
+     */
+    protected function getSimpleXmlElementNodeFromXMLReader($xmlReader)
+    {
+        $node = null;
+        try {
+            $node = new SimpleXMLElement($xmlReader->readOuterXml());
+        } catch (XMLProcessingException $exception) {
+            throw new IOException("The sharedStrings.xml file contains unreadable data [{$exception->getMessage()}].");
+        }
+
+        return $node;
+    }
+
+    /**
+     * Removes nodes that should not be read, like the pronunciation of the Kanji characters.
+     * By keeping them, their text content would be added to the read string.
+     *
+     * @param \Box\Spout\Reader\Wrapper\SimpleXMLElement $parentNode Parent node that may contain nodes to remove
+     * @return \Box\Spout\Reader\Wrapper\SimpleXMLElement Cleaned parent node
+     */
+    protected function removeSuperfluousTextNodes($parentNode)
+    {
+        $tagsToRemove = [
+            'rPh', // Pronunciation of the text
+        ];
+
+        foreach ($tagsToRemove as $tagToRemove) {
+            $xpath = '//ns:' . $tagToRemove;
+            $parentNode->removeNodesMatchingXPath($xpath);
+        }
+
+        return $parentNode;
+    }
+
+    /**
+     * If the text node has the attribute 'xml:space="preserve"', then preserve whitespace.
+     *
+     * @param \Box\Spout\Reader\Wrapper\SimpleXMLElement $textNode The text node element (<t>) whitespace may be preserved
+     * @return bool Whether whitespace should be preserved
+     */
+    protected function shouldPreserveWhitespace($textNode)
+    {
+        $spaceValue = $textNode->getAttribute('space', 'xml');
+        return ($spaceValue === 'preserve');
+    }
+
+    /**
+     * Returns the shared string at the given index, using the previously chosen caching strategy.
+     *
+     * @param int $sharedStringIndex Index of the shared string in the sharedStrings.xml file
+     * @return string The shared string at the given index
+     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If no shared string found for the given index
+     */
+    public function getStringAtIndex($sharedStringIndex)
+    {
+        return $this->cachingStrategy->getStringAtIndex($sharedStringIndex);
+    }
+
+    /**
+     * Destroys the cache, freeing memory and removing any created artifacts
+     *
+     * @return void
+     */
+    public function cleanup()
+    {
+        if ($this->cachingStrategy) {
+            $this->cachingStrategy->clearCache();
+        }
+    }
+}

src/Spout/Reader/XLSX/Helper/SheetHelper.php

@@ -1,17 +1,17 @@
 <?php
 
-namespace Box\Spout\Reader\Helper\XLSX;
+namespace Box\Spout\Reader\XLSX\Helper;
 
-use Box\Spout\Reader\Internal\XLSX\Worksheet;
-use Box\Spout\Reader\Sheet;
+use Box\Spout\Reader\Wrapper\SimpleXMLElement;
+use Box\Spout\Reader\XLSX\Sheet;
 
 /**
- * Class WorksheetHelper
- * This class provides helper functions related to XLSX worksheets
+ * Class SheetHelper
+ * This class provides helper functions related to XLSX sheets
  *
- * @package Box\Spout\Reader\Helper\XLSX
+ * @package Box\Spout\Reader\XLSX\Helper
  */
-class WorksheetHelper
+class SheetHelper
 {
     /** Extension for XML files */
     const XML_EXTENSION = '.xml';
@@ -26,58 +26,63 @@ class WorksheetHelper
     const MAIN_NAMESPACE_FOR_WORKBOOK_XML_RELS = 'http://schemas.openxmlformats.org/package/2006/relationships';
     const MAIN_NAMESPACE_FOR_WORKBOOK_XML = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
 
-    /** Value of the Override attribute used in [Content_Types].xml to define worksheets */
+    /** Value of the Override attribute used in [Content_Types].xml to define sheets */
     const OVERRIDE_CONTENT_TYPES_ATTRIBUTE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml';
 
     /** @var string Path of the XLSX file being read */
     protected $filePath;
 
+    /** @var \Box\Spout\Reader\XLSX\Helper\SharedStringsHelper Helper to work with shared strings */
+    protected $sharedStringsHelper;
+
     /** @var \Box\Spout\Common\Helper\GlobalFunctionsHelper Helper to work with global functions */
     protected $globalFunctionsHelper;
 
-    /** @var \SimpleXMLElement XML element representing the workbook.xml.rels file */
+    /** @var \Box\Spout\Reader\Wrapper\SimpleXMLElement XML element representing the workbook.xml.rels file */
     protected $workbookXMLRelsAsXMLElement;
 
-    /** @var \SimpleXMLElement XML element representing the workbook.xml file */
+    /** @var \Box\Spout\Reader\Wrapper\SimpleXMLElement XML element representing the workbook.xml file */
     protected $workbookXMLAsXMLElement;
 
     /**
      * @param string $filePath Path of the XLSX file being read
+     * @param \Box\Spout\Reader\XLSX\Helper\SharedStringsHelper Helper to work with shared strings
      * @param \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
      */
-    public function __construct($filePath, $globalFunctionsHelper)
+    public function __construct($filePath, $sharedStringsHelper, $globalFunctionsHelper)
     {
         $this->filePath = $filePath;
+        $this->sharedStringsHelper = $sharedStringsHelper;
         $this->globalFunctionsHelper = $globalFunctionsHelper;
     }
 
     /**
-     * Returns the file paths of the worksheet data XML files within the XLSX file.
-     * The paths are read from the [Content_Types].xml file.
+     * Returns the sheets metadata of the file located at the previously given file path.
+     * The paths to the sheets' data are read from the [Content_Types].xml file.
      *
-     * @return Worksheet[] Worksheets within the XLSX file
+     * @return Sheet[] Sheets within the XLSX file
      */
-    public function getWorksheets()
+    public function getSheets()
     {
-        $worksheets = [];
+        $sheets = [];
 
         $contentTypesAsXMLElement = $this->getFileAsXMLElementWithNamespace(
             self::CONTENT_TYPES_XML_FILE_PATH,
             self::MAIN_NAMESPACE_FOR_CONTENT_TYPES_XML
         );
 
-        // find all nodes defining a worksheet
+        // find all nodes defining a sheet
         $sheetNodes = $contentTypesAsXMLElement->xpath('//ns:Override[@ContentType="' . self::OVERRIDE_CONTENT_TYPES_ATTRIBUTE . '"]');
+        $numSheetNodes = count($sheetNodes);
 
-        for ($i = 0; $i < count($sheetNodes); $i++) {
+        for ($i = 0; $i < $numSheetNodes; $i++) {
             $sheetNode = $sheetNodes[$i];
-            $sheetDataXMLFilePath = (string) $sheetNode->attributes()->PartName;
+            $sheetDataXMLFilePath = $sheetNode->getAttribute('PartName');
 
-            $sheet = $this->getSheet($sheetDataXMLFilePath, $i);
-            $worksheets[] = new Worksheet($sheet, $i, $sheetDataXMLFilePath);
+            $sheets[] = $this->getSheetFromXML($sheetDataXMLFilePath, $i);
         }
 
-        return $worksheets;
+        return $sheets;
     }
 
     /**
@@ -92,9 +97,9 @@ class WorksheetHelper
      *
      * @param string $sheetDataXMLFilePath Path of the sheet data XML file as in [Content_Types].xml
      * @param int $sheetIndexZeroBased Index of the sheet, based on order in [Content_Types].xml (zero-based)
-     * @return \Box\Spout\Reader\Sheet Sheet instance
+     * @return \Box\Spout\Reader\XLSX\Sheet Sheet instance
      */
-    protected function getSheet($sheetDataXMLFilePath, $sheetIndexZeroBased)
+    protected function getSheetFromXML($sheetDataXMLFilePath, $sheetIndexZeroBased)
     {
         $sheetId = $sheetIndexZeroBased + 1;
         $sheetName = $this->getDefaultSheetName($sheetDataXMLFilePath);
@@ -111,29 +116,29 @@ class WorksheetHelper
 
         if (count($relationshipNodes) === 1) {
             $relationshipNode = $relationshipNodes[0];
-            $sheetId = (string) $relationshipNode->attributes()->Id;
+            $sheetId = $relationshipNode->getAttribute('Id');
 
             $workbookXMLElement = $this->getWorkbookXMLAsXMLElement();
             $sheetNodes = $workbookXMLElement->xpath('//ns:sheet[@r:id="' . $sheetId . '"]');
 
             if (count($sheetNodes) === 1) {
                 $sheetNode = $sheetNodes[0];
-                $sheetId = (int) $sheetNode->attributes()->sheetId;
-                $escapedSheetName = (string) $sheetNode->attributes()->name;
+                $sheetId = (int) $sheetNode->getAttribute('sheetId');
+                $escapedSheetName = $sheetNode->getAttribute('name');
 
                 $escaper = new \Box\Spout\Common\Escaper\XLSX();
                 $sheetName = $escaper->unescape($escapedSheetName);
             }
         }
 
-        return new Sheet($sheetId, $sheetIndexZeroBased, $sheetName);
+        return new Sheet($this->filePath, $sheetDataXMLFilePath, $this->sharedStringsHelper, $sheetId, $sheetIndexZeroBased, $sheetName);
     }
 
     /**
      * Returns the default name of the sheet whose data is located
      * at the given path.
      *
-     * @param $sheetDataXMLFilePath
+     * @param string $sheetDataXMLFilePath Path of the sheet data XML file
      * @return string The default sheet name
      */
     protected function getDefaultSheetName($sheetDataXMLFilePath)
@@ -145,7 +150,7 @@ class WorksheetHelper
      * Returns a representation of the workbook.xml.rels file, ready to be parsed.
      * The returned value is cached.
      *
-     * @return \SimpleXMLElement XML element representating the workbook.xml.rels file
+     * @return \Box\Spout\Reader\Wrapper\SimpleXMLElement XML element representating the workbook.xml.rels file
      */
     protected function getWorkbookXMLRelsAsXMLElement()
     {
@@ -163,7 +168,7 @@ class WorksheetHelper
      * Returns a representation of the workbook.xml file, ready to be parsed.
      * The returned value is cached.
      *
-     * @return \SimpleXMLElement XML element representating the workbook.xml.rels file
+     * @return \Box\Spout\Reader\Wrapper\SimpleXMLElement XML element representating the workbook.xml.rels file
      */
     protected function getWorkbookXMLAsXMLElement()
     {
@@ -182,29 +187,15 @@ class WorksheetHelper
      *
      * @param string $xmlFilePath The path of the XML file inside the XLSX file
      * @param string $mainNamespace The main XPath namespace to register
-     * @return \SimpleXMLElement The XML element representing the file
+     * @return \Box\Spout\Reader\Wrapper\SimpleXMLElement The XML element representing the file
      */
     protected function getFileAsXMLElementWithNamespace($xmlFilePath, $mainNamespace)
     {
-        $normalizedXmlFilePath = str_replace('/', DIRECTORY_SEPARATOR, $xmlFilePath);
-        $xmlContents = $this->globalFunctionsHelper->file_get_contents('zip://' . $this->filePath . '#' . $normalizedXmlFilePath);
+        $xmlContents = $this->globalFunctionsHelper->file_get_contents('zip://' . $this->filePath . '#' . $xmlFilePath);
 
-        $xmlElement = new \SimpleXMLElement($xmlContents);
+        $xmlElement = new SimpleXMLElement($xmlContents);
         $xmlElement->registerXPathNamespace('ns', $mainNamespace);
 
         return $xmlElement;
     }
-
-    /**
-     * Returns whether another worksheet exists after the current worksheet.
-     * The order is determined by the order of appearance in the [Content_Types].xml file.
-     *
-     * @param Worksheet|null $currentWorksheet The worksheet being currently read or null if reading has not started yet
-     * @param Worksheet[] $allWorksheets A list of all worksheets in the XLSX file. Must contain at least one worksheet
-     * @return bool Whether another worksheet exists after the current sheet
-     */
-    public function hasNextWorksheet($currentWorksheet, $allWorksheets)
-    {
-        return ($currentWorksheet === null || ($currentWorksheet->getWorksheetIndex() + 1 < count($allWorksheets)));
-    }
 }

src/Spout/Reader/XLSX/Reader.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX;
+
+use Box\Spout\Common\Exception\IOException;
+use Box\Spout\Reader\AbstractReader;
+use Box\Spout\Reader\XLSX\Helper\SharedStringsHelper;
+
+/**
+ * Class Reader
+ * This class provides support to read data from a XLSX file
+ *
+ * @package Box\Spout\Reader\XLSX
+ */
+class Reader extends AbstractReader
+{
+    /** @var string Temporary folder where the temporary files will be created */
+    protected $tempFolder;
+
+    /** @var \ZipArchive */
+    protected $zip;
+
+    /** @var \Box\Spout\Reader\XLSX\Helper\SharedStringsHelper Helper to work with shared strings */
+    protected $sharedStringsHelper;
+
+    /** @var SheetIterator To iterator over the XLSX sheets */
+    protected $sheetIterator;
+
+
+    /**
+     * @param string $tempFolder Temporary folder where the temporary files will be created
+     * @return Reader
+     */
+    public function setTempFolder($tempFolder)
+    {
+        $this->tempFolder = $tempFolder;
+        return $this;
+    }
+
+    /**
+     * Opens the file at the given file path to make it ready to be read.
+     * It also parses the sharedStrings.xml file to get all the shared strings available in memory
+     * and fetches all the available sheets.
+     *
+     * @param  string $filePath Path of the file to be read
+     * @return void
+     * @throws \Box\Spout\Common\Exception\IOException If the file at the given path or its content cannot be read
+     * @throws \Box\Spout\Reader\Exception\NoSheetsFoundException If there are no sheets in the file
+     */
+    protected function openReader($filePath)
+    {
+        $this->zip = new \ZipArchive();
+
+        if ($this->zip->open($filePath) === true) {
+            $this->sharedStringsHelper = new SharedStringsHelper($filePath, $this->tempFolder);
+
+            if ($this->sharedStringsHelper->hasSharedStrings()) {
+                // Extracts all the strings from the sheets for easy access in the future
+                $this->sharedStringsHelper->extractSharedStrings();
+            }
+
+            $this->sheetIterator = new SheetIterator($filePath, $this->sharedStringsHelper, $this->globalFunctionsHelper);
+        } else {
+            throw new IOException("Could not open $filePath for reading.");
+        }
+    }
+
+    /**
+     * Returns an iterator to iterate over sheets.
+     *
+     * @return SheetIterator To iterate over sheets
+     */
+    public function getConcreteSheetIterator()
+    {
+        return $this->sheetIterator;
+    }
+
+    /**
+     * Closes the reader. To be used after reading the file.
+     *
+     * @return void
+     */
+    protected function closeReader()
+    {
+        if ($this->zip) {
+            $this->zip->close();
+        }
+
+        if ($this->sharedStringsHelper) {
+            $this->sharedStringsHelper->cleanup();
+        }
+    }
+}

src/Spout/Reader/XLSX/RowIterator.php

@@ -0,0 +1,364 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX;
+
+use Box\Spout\Common\Exception\IOException;
+use Box\Spout\Reader\Exception\XMLProcessingException;
+use Box\Spout\Reader\IteratorInterface;
+use Box\Spout\Reader\Wrapper\XMLReader;
+use Box\Spout\Reader\XLSX\Helper\CellHelper;
+
+/**
+ * Class RowIterator
+ *
+ * @package Box\Spout\Reader\XLSX
+ */
+class RowIterator implements IteratorInterface
+{
+    /** Definition of all possible cell types */
+    const CELL_TYPE_INLINE_STRING = 'inlineStr';
+    const CELL_TYPE_STR = 'str';
+    const CELL_TYPE_SHARED_STRING = 's';
+    const CELL_TYPE_BOOLEAN = 'b';
+    const CELL_TYPE_NUMERIC = 'n';
+    const CELL_TYPE_DATE = 'd';
+    const CELL_TYPE_ERROR = 'e';
+
+    /** Definition of XML nodes names used to parse data */
+    const XML_NODE_DIMENSION = 'dimension';
+    const XML_NODE_WORKSHEET = 'worksheet';
+    const XML_NODE_ROW = 'row';
+    const XML_NODE_CELL = 'c';
+    const XML_NODE_VALUE = 'v';
+    const XML_NODE_INLINE_STRING_VALUE = 't';
+
+    /** Definition of XML attributes used to parse data */
+    const XML_ATTRIBUTE_REF = 'ref';
+    const XML_ATTRIBUTE_SPANS = 'spans';
+    const XML_ATTRIBUTE_CELL_INDEX = 'r';
+    const XML_ATTRIBUTE_TYPE = 't';
+
+    /** @var string Path of the XLSX file being read */
+    protected $filePath;
+
+    /** @var string $sheetDataXMLFilePath Path of the sheet data XML file as in [Content_Types].xml */
+    protected $sheetDataXMLFilePath;
+
+    /** @var Helper\SharedStringsHelper Helper to work with shared strings */
+    protected $sharedStringsHelper;
+
+    /** @var \Box\Spout\Reader\Wrapper\XMLReader The XMLReader object that will help read sheet's XML data */
+    protected $xmlReader;
+
+    /** @var \Box\Spout\Common\Escaper\XLSX Used to unescape XML data */
+    protected $escaper;
+
+    /** @var int Number of read rows */
+    protected $numReadRows = 0;
+
+    /** @var array|null Buffer used to store the row data, while checking if there are more rows to read */
+    protected $rowDataBuffer = null;
+
+    /** @var bool Indicates whether all rows have been read */
+    protected $hasReachedEndOfFile = false;
+
+    /** @var int The number of columns the sheet has (0 meaning undefined) */
+    protected $numColumns = 0;
+
+    /**
+     * @param string $filePath Path of the XLSX file being read
+     * @param string $sheetDataXMLFilePath Path of the sheet data XML file as in [Content_Types].xml
+     * @param Helper\SharedStringsHelper $sharedStringsHelper Helper to work with shared strings
+     */
+    public function __construct($filePath, $sheetDataXMLFilePath, $sharedStringsHelper)
+    {
+        $this->filePath = $filePath;
+        $this->sheetDataXMLFilePath = $this->normalizeSheetDataXMLFilePath($sheetDataXMLFilePath);
+        $this->sharedStringsHelper = $sharedStringsHelper;
+
+        $this->xmlReader = new XMLReader();
+        $this->escaper = new \Box\Spout\Common\Escaper\XLSX();
+    }
+
+    /**
+     * @param string $sheetDataXMLFilePath Path of the sheet data XML file as in [Content_Types].xml
+     * @return string Path of the XML file containing the sheet data,
+     *                without the leading slash.
+     */
+    protected function normalizeSheetDataXMLFilePath($sheetDataXMLFilePath)
+    {
+        return ltrim($sheetDataXMLFilePath, '/');
+    }
+
+    /**
+     * Rewind the Iterator to the first element.
+     * Initializes the XMLReader object that reads the associated sheet data.
+     * The XMLReader is configured to be safe from billion laughs attack.
+     * @link http://php.net/manual/en/iterator.rewind.php
+     *
+     * @return void
+     * @throws \Box\Spout\Common\Exception\IOException If the sheet data XML cannot be read
+     */
+    public function rewind()
+    {
+        $this->xmlReader->close();
+
+        $sheetDataFilePath = 'zip://' . $this->filePath . '#' . $this->sheetDataXMLFilePath;
+        if ($this->xmlReader->open($sheetDataFilePath) === false) {
+            throw new IOException("Could not open \"{$this->sheetDataXMLFilePath}\".");
+        }
+
+        $this->numReadRows = 0;
+        $this->rowDataBuffer = null;
+        $this->hasReachedEndOfFile = false;
+        $this->numColumns = 0;
+
+        $this->next();
+    }
+
+    /**
+     * Checks if current position is valid
+     * @link http://php.net/manual/en/iterator.valid.php
+     *
+     * @return boolean
+     */
+    public function valid()
+    {
+        return (!$this->hasReachedEndOfFile);
+    }
+
+    /**
+     * Move forward to next element. Empty rows will be skipped.
+     * @link http://php.net/manual/en/iterator.next.php
+     *
+     * @return void
+     * @throws \Box\Spout\Reader\Exception\SharedStringNotFoundException If a shared string was not found
+     * @throws \Box\Spout\Common\Exception\IOException If unable to read the sheet data XML
+     */
+    public function next()
+    {
+        $isInsideRowTag = false;
+        $rowData = [];
+
+        try {
+            while ($this->xmlReader->read()) {
+                if ($this->xmlReader->nodeType == XMLReader::ELEMENT && $this->xmlReader->name === self::XML_NODE_DIMENSION) {
+                    // Read dimensions of the sheet
+                    $dimensionRef = $this->xmlReader->getAttribute(self::XML_ATTRIBUTE_REF); // returns 'A1:M13' for instance (or 'A1' for empty sheet)
+                    if (preg_match('/[A-Z\d]+:([A-Z\d]+)/', $dimensionRef, $matches)) {
+                        $lastCellIndex = $matches[1];
+                        $this->numColumns = CellHelper::getColumnIndexFromCellIndex($lastCellIndex) + 1;
+                    }
+
+                } else if ($this->xmlReader->nodeType == XMLReader::ELEMENT && $this->xmlReader->name === self::XML_NODE_ROW) {
+                    // Start of the row description
+                    $isInsideRowTag = true;
+
+                    // Read spans info if present
+                    $numberOfColumnsForRow = $this->numColumns;
+                    $spans = $this->xmlReader->getAttribute(self::XML_ATTRIBUTE_SPANS); // returns '1:5' for instance
+                    if ($spans) {
+                        list(, $numberOfColumnsForRow) = explode(':', $spans);
+                        $numberOfColumnsForRow = intval($numberOfColumnsForRow);
+                    }
+                    $rowData = ($numberOfColumnsForRow !== 0) ? array_fill(0, $numberOfColumnsForRow, '') : [];
+
+                } else if ($isInsideRowTag && $this->xmlReader->nodeType == XMLReader::ELEMENT && $this->xmlReader->name === self::XML_NODE_CELL) {
+                    // Start of a cell description
+                    $currentCellIndex = $this->xmlReader->getAttribute(self::XML_ATTRIBUTE_CELL_INDEX);
+                    $currentColumnIndex = CellHelper::getColumnIndexFromCellIndex($currentCellIndex);
+
+                    $node = $this->xmlReader->expand();
+                    $rowData[$currentColumnIndex] = $this->getCellValue($node);
+
+                } else if ($this->xmlReader->nodeType == XMLReader::END_ELEMENT && $this->xmlReader->name === self::XML_NODE_ROW) {
+                    // End of the row description
+                    // If needed, we fill the empty cells
+                    $rowData = ($this->numColumns !== 0) ? $rowData : CellHelper::fillMissingArrayIndexes($rowData);
+                    $this->numReadRows++;
+                    break;
+
+                } else if ($this->xmlReader->nodeType == XMLReader::END_ELEMENT && $this->xmlReader->name === self::XML_NODE_WORKSHEET) {
+                    // The closing "</worksheet>" marks the end of the file
+                    $this->hasReachedEndOfFile = true;
+                }
+            }
+
+        } catch (XMLProcessingException $exception) {
+            throw new IOException("The {$this->sheetDataXMLFilePath} file cannot be read. [{$exception->getMessage()}]");
+        }
+
+        $this->rowDataBuffer = $rowData;
+    }
+
+    /**
+     * Returns the cell's string value from a node's nested value node
+     *
+     * @param \DOMNode $node
+     * @return string The value associated with the cell
+     */
+    protected function getVNodeValue($node)
+    {
+        // for cell types having a "v" tag containing the value.
+        // if not, the returned value should be empty string.
+        $vNode = $node->getElementsByTagName(self::XML_NODE_VALUE)->item(0);
+        if ($vNode !== null) {
+            return $vNode->nodeValue;
+        }
+        return "";
+    }
+
+    /**
+     * Returns the cell String value where string is inline.
+     *
+     * @param \DOMNode $node
+     * @return string The value associated with the cell (null when the cell has an error)
+     */
+    protected function formatInlineStringCellValue($node)
+    {
+        // inline strings are formatted this way:
+        // <c r="A1" t="inlineStr"><is><t>[INLINE_STRING]</t></is></c>
+        $tNode = $node->getElementsByTagName(self::XML_NODE_INLINE_STRING_VALUE)->item(0);
+        $escapedCellValue = trim($tNode->nodeValue);
+        $cellValue = $this->escaper->unescape($escapedCellValue);
+        return $cellValue;
+    }
+
+    /**
+     * Returns the cell String value from shared-strings file using nodeValue index.
+     *
+     * @param string $nodeValue
+     * @return string The value associated with the cell (null when the cell has an error)
+     */
+    protected function formatSharedStringCellValue($nodeValue)
+    {
+        // shared strings are formatted this way:
+        // <c r="A1" t="s"><v>[SHARED_STRING_INDEX]</v></c>
+        $sharedStringIndex = intval($nodeValue);
+        $escapedCellValue = $this->sharedStringsHelper->getStringAtIndex($sharedStringIndex);
+        $cellValue = $this->escaper->unescape($escapedCellValue);
+        return $cellValue;
+    }
+
+    /**
+     * Returns the cell String value, where string is stored in value node.
+     *
+     * @param string $nodeValue
+     * @return string The value associated with the cell (null when the cell has an error)
+     */
+    protected function formatStrCellValue($nodeValue)
+    {
+        $escapedCellValue = trim($nodeValue);
+        $cellValue = $this->escaper->unescape($escapedCellValue);
+        return $cellValue;
+    }
+
+    /**
+     * Returns the cell Numeric value from string of nodeValue.
+     *
+     * @param string $nodeValue
+     * @return int|float The value associated with the cell
+     */
+    protected function formatNumericCellValue($nodeValue)
+    {
+        $cellValue = is_int($nodeValue) ? intval($nodeValue) : floatval($nodeValue);
+        return $cellValue;
+    }
+
+    /**
+     * Returns the cell Boolean value from a specific node's Value.
+     *
+     * @param string $nodeValue
+     * @return bool The value associated with the cell
+     */
+    protected function formatBooleanCellValue($nodeValue)
+    {
+        // !! is similar to boolval()
+        $cellValue = !!$nodeValue;
+        return $cellValue;
+    }
+
+    /**
+     * Returns a cell's PHP Date value, associated to the given stored nodeValue.
+     *
+     * @param string $nodeValue
+     * @return \DateTime|null The value associated with the cell (null when the cell has an error)
+     */
+    protected function formatDateCellValue($nodeValue)
+    {
+        // Mitigate thrown Exception on invalid date-time format (http://php.net/manual/en/datetime.construct.php)
+        try {
+            $cellValue = new \DateTime($nodeValue);
+            return $cellValue;
+        } catch (\Exception $e) {
+            return null;
+        }
+    }
+
+    /**
+     * Returns the (unescaped) correctly marshalled, cell value associated to the given XML node.
+     *
+     * @param \DOMNode $node
+     * @return string|int|float|bool|\DateTime|null The value associated with the cell (null when the cell has an error)
+     */
+    protected function getCellValue($node)
+    {
+        // Default cell type is "n"
+        $cellType = $node->getAttribute(self::XML_ATTRIBUTE_TYPE) ?: self::CELL_TYPE_NUMERIC;
+        $vNodeValue = $this->getVNodeValue($node);
+
+        if (($vNodeValue === '') && ($cellType !== self::CELL_TYPE_INLINE_STRING)) {
+            return $vNodeValue;
+        }
+
+        switch ($cellType) {
+            case self::CELL_TYPE_INLINE_STRING:
+                return $this->formatInlineStringCellValue($node);
+            case self::CELL_TYPE_SHARED_STRING:
+                return $this->formatSharedStringCellValue($vNodeValue);
+            case self::CELL_TYPE_STR:
+                return $this->formatStrCellValue($vNodeValue);
+            case self::CELL_TYPE_BOOLEAN:
+                return $this->formatBooleanCellValue($vNodeValue);
+            case self::CELL_TYPE_NUMERIC:
+                return $this->formatNumericCellValue($vNodeValue);
+            case self::CELL_TYPE_DATE:
+                return $this->formatDateCellValue($vNodeValue);
+            default:
+                return null;
+        }
+    }
+
+    /**
+     * Return the current element, from the buffer.
+     * @link http://php.net/manual/en/iterator.current.php
+     *
+     * @return array|null
+     */
+    public function current()
+    {
+        return $this->rowDataBuffer;
+    }
+
+    /**
+     * Return the key of the current element
+     * @link http://php.net/manual/en/iterator.key.php
+     *
+     * @return int
+     */
+    public function key()
+    {
+        return $this->numReadRows;
+    }
+
+
+    /**
+     * Cleans up what was created to iterate over the object.
+     *
+     * @return void
+     */
+    public function end()
+    {
+        $this->xmlReader->close();
+    }
+}

src/Spout/Reader/XLSX/Sheet.php

@@ -1,15 +1,20 @@
 <?php
 
-namespace Box\Spout\Reader;
+namespace Box\Spout\Reader\XLSX;
+
+use Box\Spout\Reader\SheetInterface;
 
 /**
  * Class Sheet
- * Represents a worksheet within a XLSX file
+ * Represents a sheet within a XLSX file
  *
- * @package Box\Spout\Reader
+ * @package Box\Spout\Reader\XLSX
  */
-class Sheet
+class Sheet implements SheetInterface
 {
+    /** @var RowIterator To iterate over sheet's rows */
+    protected $rowIterator;
+
     /** @var int ID of the sheet */
     protected $id;
 
@@ -20,17 +25,29 @@ class Sheet
     protected $name;
 
     /**
+     * @param string $filePath Path of the XLSX file being read
+     * @param string $sheetDataXMLFilePath Path of the sheet data XML file as in [Content_Types].xml
+     * @param Helper\SharedStringsHelper Helper to work with shared strings
      * @param int $sheetId ID of the sheet
      * @param int $sheetIndex Index of the sheet, based on order of creation (zero-based)
      * @param string $sheetName Name of the sheet
      */
-    function __construct($sheetId, $sheetIndex, $sheetName)
+    public function __construct($filePath, $sheetDataXMLFilePath, $sharedStringsHelper, $sheetId, $sheetIndex, $sheetName)
     {
+        $this->rowIterator = new RowIterator($filePath, $sheetDataXMLFilePath, $sharedStringsHelper);
         $this->id = $sheetId;
         $this->index = $sheetIndex;
         $this->name = $sheetName;
     }
 
+    /**
+     * @return RowIterator
+     */
+    public function getRowIterator()
+    {
+        return $this->rowIterator;
+    }
+
     /**
      * @return int ID of the sheet
      */

src/Spout/Reader/XLSX/SheetIterator.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX;
+
+use Box\Spout\Reader\IteratorInterface;
+use Box\Spout\Reader\XLSX\Helper\SheetHelper;
+use Box\Spout\Reader\Exception\NoSheetsFoundException;
+
+/**
+ * Class SheetIterator
+ * Iterate over XLSX sheet.
+ *
+ * @package Box\Spout\Reader\XLSX
+ */
+class SheetIterator implements IteratorInterface
+{
+    /** @var Sheet[] The list of sheet present in the file */
+    protected $sheets;
+
+    /** @var int The index of the sheet being read (zero-based) */
+    protected $currentSheetIndex;
+
+    /**
+     * @param string $filePath Path of the file to be read
+     * @param \Box\Spout\Reader\XLSX\Helper\SharedStringsHelper $sharedStringsHelper
+     * @param \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     * @throws \Box\Spout\Reader\Exception\NoSheetsFoundException If there are no sheets in the file
+     */
+    public function __construct($filePath, $sharedStringsHelper, $globalFunctionsHelper)
+    {
+        // Fetch all available sheets
+        $sheetHelper = new SheetHelper($filePath, $sharedStringsHelper, $globalFunctionsHelper);
+        $this->sheets = $sheetHelper->getSheets();
+
+        if (count($this->sheets) === 0) {
+            throw new NoSheetsFoundException('The file must contain at least one sheet.');
+        }
+    }
+
+    /**
+     * Rewind the Iterator to the first element
+     * @link http://php.net/manual/en/iterator.rewind.php
+     *
+     * @return void
+     */
+    public function rewind()
+    {
+        $this->currentSheetIndex = 0;
+    }
+
+    /**
+     * Checks if current position is valid
+     * @link http://php.net/manual/en/iterator.valid.php
+     *
+     * @return boolean
+     */
+    public function valid()
+    {
+        return ($this->currentSheetIndex < count($this->sheets));
+    }
+
+    /**
+     * Move forward to next element
+     * @link http://php.net/manual/en/iterator.next.php
+     *
+     * @return void
+     */
+    public function next()
+    {
+        if (array_key_exists($this->currentSheetIndex, $this->sheets)) {
+            $currentSheet = $this->sheets[$this->currentSheetIndex];
+            $currentSheet->getRowIterator()->end();
+
+            $this->currentSheetIndex++;
+        }
+    }
+
+    /**
+     * Return the current element
+     * @link http://php.net/manual/en/iterator.current.php
+     *
+     * @return Sheet
+     */
+    public function current()
+    {
+        return $this->sheets[$this->currentSheetIndex];
+    }
+
+    /**
+     * Return the key of the current element
+     * @link http://php.net/manual/en/iterator.key.php
+     *
+     * @return int
+     */
+    public function key()
+    {
+        return $this->currentSheetIndex + 1;
+    }
+
+    /**
+     * Cleans up what was created to iterate over the object.
+     *
+     * @return void
+     */
+    public function end()
+    {
+        // make sure we are not leaking memory in case the iteration stopped before the end
+        foreach ($this->sheets as $sheet) {
+            $sheet->getRowIterator()->end();
+        }
+    }
+}

src/Spout/Writer/AbstractWriter.php

@@ -69,7 +69,7 @@ abstract class AbstractWriter implements WriterInterface
      * By using this method, the data will be written to a file.
      *
      * @param  string $outputFilePath Path of the output file that will contain the data
-     * @return \Box\Spout\Writer\AbstractWriter
+     * @return AbstractWriter
      * @throws \Box\Spout\Common\Exception\IOException If the writer cannot be opened or if the given path is not writable
      */
     public function openToFile($outputFilePath)
@@ -92,7 +92,7 @@ abstract class AbstractWriter implements WriterInterface
      * @codeCoverageIgnore
      *
      * @param  string $outputFileName Name of the output file that will contain the data. If a path is passed in, only the file name will be kept
-     * @return \Box\Spout\Writer\AbstractWriter
+     * @return AbstractWriter
      * @throws \Box\Spout\Common\Exception\IOException If the writer cannot be opened
      */
     public function openToBrowser($outputFileName)
@@ -144,7 +144,7 @@ abstract class AbstractWriter implements WriterInterface
      *                        If empty, no data is added (i.e. not even as a blank row)
      *                        Example: $dataRow = ['data1', 1234, null, '', 'data5', false];
      *
-     * @return \Box\Spout\Writer\AbstractWriter
+     * @return AbstractWriter
      * @throws \Box\Spout\Writer\Exception\WriterNotOpenedException If this function is called before opening the writer
      * @throws \Box\Spout\Common\Exception\IOException If unable to write data
      */
@@ -173,7 +173,7 @@ abstract class AbstractWriter implements WriterInterface
      *                             ['data21', 'data22', null, false],
      *                         ];
      *
-     * @return \Box\Spout\Writer\AbstractWriter
+     * @return AbstractWriter
      * @throws \Box\Spout\Common\Exception\InvalidArgumentException If the input param is not valid
      * @throws \Box\Spout\Writer\Exception\WriterNotOpenedException If this function is called before opening the writer
      * @throws \Box\Spout\Common\Exception\IOException If unable to write data

src/Spout/Writer/CSV/Writer.php

@@ -1,20 +1,21 @@
 <?php
 
-namespace Box\Spout\Writer;
+namespace Box\Spout\Writer\CSV;
 
+use Box\Spout\Writer\AbstractWriter;
 use Box\Spout\Common\Exception\IOException;
+use Box\Spout\Common\Helper\EncodingHelper;
 
 /**
- * Class CSV
+ * Class Writer
  * This class provides support to write data to CSV files
  *
- * @package Box\Spout\Writer
+ * @package Box\Spout\Writer\CSV
  */
-class CSV extends AbstractWriter
+class Writer extends AbstractWriter
 {
     /** Number of rows to write before flushing */
     const FLUSH_THRESHOLD = 500;
-    const UTF8_BOM = "\xEF\xBB\xBF";
 
     /** @var string Content-Type value for the header */
     protected static $headerContentType = 'text/csv; charset=UTF-8';
@@ -32,7 +33,7 @@ class CSV extends AbstractWriter
      * Sets the field delimiter for the CSV
      *
      * @param string $fieldDelimiter Character that delimits fields
-     * @return CSV
+     * @return Writer
      */
     public function setFieldDelimiter($fieldDelimiter)
     {
@@ -44,7 +45,7 @@ class CSV extends AbstractWriter
      * Sets the field enclosure for the CSV
      *
      * @param string $fieldEnclosure Character that enclose fields
-     * @return CSV
+     * @return Writer
      */
     public function setFieldEnclosure($fieldEnclosure)
     {
@@ -60,7 +61,7 @@ class CSV extends AbstractWriter
     protected function openWriter()
     {
         // Adds UTF-8 BOM for Unicode compatibility
-        $this->globalFunctionsHelper->fputs($this->filePointer, self::UTF8_BOM);
+        $this->globalFunctionsHelper->fputs($this->filePointer, EncodingHelper::BOM_UTF8);
     }
 
     /**

src/Spout/Writer/WriterFactory.php

@@ -19,7 +19,7 @@ class WriterFactory
      * This creates an instance of the appropriate writer, given the type of the file to be read
      *
      * @param  string $writerType Type of the writer to instantiate
-     * @return \Box\Spout\Writer\CSV|\Box\Spout\Writer\XLSX
+     * @return WriterInterface
      * @throws \Box\Spout\Common\Exception\UnsupportedTypeException
      */
     public static function create($writerType)
@@ -28,10 +28,10 @@ class WriterFactory
 
         switch ($writerType) {
             case Type::CSV:
-                $writer = new CSV();
+                $writer = new CSV\Writer();
                 break;
             case Type::XLSX:
-                $writer = new XLSX();
+                $writer = new XLSX\Writer();
                 break;
             default:
                 throw new UnsupportedTypeException('No writers supporting the given type: ' . $writerType);

src/Spout/Writer/WriterInterface.php

@@ -14,7 +14,7 @@ interface WriterInterface
      * By using this method, the data will be written to a file.
      *
      * @param  string $outputFilePath Path of the output file that will contain the data
-     * @return \Box\Spout\Writer\WriterInterface
+     * @return WriterInterface
      * @throws \Box\Spout\Common\Exception\IOException If the writer cannot be opened or if the given path is not writable
      */
     public function openToFile($outputFilePath);
@@ -24,7 +24,7 @@ interface WriterInterface
      * By using this method, the data will be outputted directly to the browser.
      *
      * @param  string $outputFileName Name of the output file that will contain the data. If a path is passed in, only the file name will be kept
-     * @return \Box\Spout\Writer\WriterInterface
+     * @return WriterInterface
      * @throws \Box\Spout\Common\Exception\IOException If the writer cannot be opened
      */
     public function openToBrowser($outputFileName);
@@ -34,7 +34,7 @@ interface WriterInterface
      *
      * @param  array $dataRow Array containing data to be streamed.
      *          Example $dataRow = ['data1', 1234, null, '', 'data5'];
-     * @return \Box\Spout\Writer\WriterInterface
+     * @return WriterInterface
      * @throws \Box\Spout\Writer\Exception\WriterNotOpenedException If the writer has not been opened yetthe writer
      * @throws \Box\Spout\Common\Exception\IOException If unable to write data
      */
@@ -48,7 +48,7 @@ interface WriterInterface
      *              ['data11', 12, , '', 'data13'],
      *              ['data21', 'data22', null],
      *          ];
-     * @return \Box\Spout\Writer\WriterInterface
+     * @return WriterInterface
      * @throws \Box\Spout\Common\Exception\InvalidArgumentException If the input param is not valid
      * @throws \Box\Spout\Writer\Exception\WriterNotOpenedException If the writer has not been opened yet
      * @throws \Box\Spout\Common\Exception\IOException If unable to write data

src/Spout/Writer/XLSX/Helper/CellHelper.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace Box\Spout\Writer\Helper\XLSX;
+namespace Box\Spout\Writer\XLSX\Helper;
 
 /**
  * Class CellHelper
  * This class provides helper functions when working with cells
  *
- * @package Box\Spout\Writer\Helper\XLSX
+ * @package Box\Spout\Writer\XLSX\Helper
  */
 class CellHelper
 {

src/Spout/Writer/XLSX/Helper/FileSystemHelper.php

@@ -1,15 +1,15 @@
 <?php
 
-namespace Box\Spout\Writer\Helper\XLSX;
+namespace Box\Spout\Writer\XLSX\Helper;
 
-use Box\Spout\Writer\Internal\XLSX\Worksheet;
+use Box\Spout\Writer\XLSX\Internal\Worksheet;
 
 /**
  * Class FileSystemHelper
  * This class provides helper functions to help with the file system operations
  * like files/folders creation & deletion for XLSX files
  *
- * @package Box\Spout\Writer\Helper\XLSX
+ * @package Box\Spout\Writer\XLSX\Helper
  */
 class FileSystemHelper extends \Box\Spout\Common\Helper\FileSystemHelper
 {

src/Spout/Writer/XLSX/Helper/SharedStringsHelper.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Box\Spout\Writer\Helper\XLSX;
+namespace Box\Spout\Writer\XLSX\Helper;
 
 use Box\Spout\Common\Exception\IOException;
 
@@ -8,7 +8,7 @@ use Box\Spout\Common\Exception\IOException;
  * Class SharedStringsHelper
  * This class provides helper functions to write shared strings
  *
- * @package Box\Spout\Writer\Helper\XLSX
+ * @package Box\Spout\Writer\XLSX\Helper
  */
 class SharedStringsHelper
 {
@@ -25,6 +25,9 @@ EOD;
      */
     const DEFAULT_STRINGS_COUNT_PART = 'count="9999999999999" uniqueCount="9999999999999"';
 
+    /** @var resource Pointer to the sharedStrings.xml file */
+    protected $sharedStringsFilePointer;
+
     /** @var int Number of shared strings already written */
     protected $numSharedStrings = 0;
 
@@ -36,7 +39,7 @@ EOD;
      */
     public function __construct($xlFolder)
     {
-        $sharedStringsFilePath = $xlFolder . DIRECTORY_SEPARATOR . self::SHARED_STRINGS_FILE_NAME;
+        $sharedStringsFilePath = $xlFolder . '/' . self::SHARED_STRINGS_FILE_NAME;
         $this->sharedStringsFilePointer = fopen($sharedStringsFilePath, 'w');
 
         $this->throwIfSharedStringsFilePointerIsNotAvailable();

src/Spout/Writer/XLSX/Helper/ZipHelper.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace Box\Spout\Writer\Helper\XLSX;
+namespace Box\Spout\Writer\XLSX\Helper;
 
 /**
  * Class ZipHelper
  * This class provides helper functions to create zip files
  *
- * @package Box\Spout\Writer\Helper\XLSX
+ * @package Box\Spout\Writer\XLSX\Helper
  */
 class ZipHelper
 {
@@ -33,18 +33,30 @@ class ZipHelper
      */
     protected function addFolderToZip($zip, $folderPath)
     {
-        $folderRealPath = realpath($folderPath) . DIRECTORY_SEPARATOR;
+        $folderRealPath = $this->getNormalizedRealPath($folderPath) . '/';
         $itemIterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($folderPath, \RecursiveDirectoryIterator::SKIP_DOTS), \RecursiveIteratorIterator::SELF_FIRST);
 
         foreach ($itemIterator as $itemInfo) {
-            $itemRealPath = realpath($itemInfo->getPathname());
+            $itemRealPath = $this->getNormalizedRealPath($itemInfo->getPathname());
             $itemLocalPath = str_replace($folderRealPath, '', $itemRealPath);
 
             if ($itemInfo->isFile()) {
-                $zip->addFile($itemInfo->getPathname(), $itemLocalPath);
+                $zip->addFile($itemRealPath, $itemLocalPath);
             } else if ($itemInfo->isDir()) {
                 $zip->addEmptyDir($itemLocalPath);
             }
         }
     }
+
+    /**
+     * Returns canonicalized absolute pathname, containing only forward slashes.
+     *
+     * @param string $path Path to normalize
+     * @return string Normalized and canonicalized path
+     */
+    protected function getNormalizedRealPath($path)
+    {
+        $realPath = realpath($path);
+        return str_replace(DIRECTORY_SEPARATOR, '/', $realPath);
+    }
 }

src/Spout/Writer/XLSX/Internal/Workbook.php

@@ -1,18 +1,18 @@
 <?php
 
-namespace Box\Spout\Writer\Internal\XLSX;
+namespace Box\Spout\Writer\XLSX\Internal;
 
 use Box\Spout\Writer\Exception\SheetNotFoundException;
-use Box\Spout\Writer\Helper\XLSX\FileSystemHelper;
-use Box\Spout\Writer\Helper\XLSX\SharedStringsHelper;
-use Box\Spout\Writer\Sheet;
+use Box\Spout\Writer\XLSX\Helper\FileSystemHelper;
+use Box\Spout\Writer\XLSX\Helper\SharedStringsHelper;
+use Box\Spout\Writer\XLSX\Sheet;
 
 /**
  * Class Book
  * Represents a workbook within a XLSX file.
  * It provides the functions to work with worksheets.
  *
- * @package Box\Spout\Writer\Internal\XLSX
+ * @package Box\Spout\Writer\XLSX\Internal
  */
 class Workbook
 {
@@ -28,10 +28,10 @@ class Workbook
     /** @var bool Whether new sheets should be automatically created when the max rows limit per sheet is reached */
     protected $shouldCreateNewSheetsAutomatically;
 
-    /** @var \Box\Spout\Writer\Helper\XLSX\FileSystemHelper Helper to perform file system operations */
+    /** @var \Box\Spout\Writer\XLSX\Helper\FileSystemHelper Helper to perform file system operations */
     protected $fileSystemHelper;
 
-    /** @var \Box\Spout\Writer\Helper\XLSX\SharedStringsHelper Helper to write shared strings */
+    /** @var \Box\Spout\Writer\XLSX\Helper\SharedStringsHelper Helper to write shared strings */
     protected $sharedStringsHelper;
 
     /** @var Worksheet[] Array containing the workbook's sheets */
@@ -114,7 +114,7 @@ class Workbook
      * Sets the given sheet as the current one. New data will be written to this sheet.
      * The writing will resume where it stopped (i.e. data won't be truncated).
      *
-     * @param \Box\Spout\Writer\Sheet $sheet The "external" sheet to set as current
+     * @param \Box\Spout\Writer\XLSX\Sheet $sheet The "external" sheet to set as current
      * @return void
      * @throws \Box\Spout\Writer\Exception\SheetNotFoundException If the given sheet does not exist in the workbook
      */
@@ -140,7 +140,7 @@ class Workbook
     /**
      * Returns the worksheet associated to the given external sheet.
      *
-     * @param \Box\Spout\Writer\Sheet $sheet
+     * @param \Box\Spout\Writer\XLSX\Sheet $sheet
      * @return Worksheet|null The worksheet associated to the given external sheet or null if not found.
      */
     protected function getWorksheetFromExternalSheet($sheet)

src/Spout/Writer/XLSX/Internal/Worksheet.php

@@ -1,17 +1,17 @@
 <?php
 
-namespace Box\Spout\Writer\Internal\XLSX;
+namespace Box\Spout\Writer\XLSX\Internal;
 
 use Box\Spout\Common\Exception\InvalidArgumentException;
 use Box\Spout\Common\Exception\IOException;
-use Box\Spout\Writer\Helper\XLSX\CellHelper;
+use Box\Spout\Writer\XLSX\Helper\CellHelper;
 
 /**
  * Class Worksheet
  * Represents a worksheet within a XLSX file. The difference with the Sheet object is
  * that this class provides an interface to write data
  *
- * @package Box\Spout\Writer\Internal\XLSX
+ * @package Box\Spout\Writer\XLSX\Internal
  */
 class Worksheet
 {
@@ -20,13 +20,13 @@ class Worksheet
 <worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
 EOD;
 
-    /** @var \Box\Spout\Writer\Sheet The "external" sheet */
+    /** @var \Box\Spout\Writer\XLSX\Sheet The "external" sheet */
     protected $externalSheet;
 
     /** @var string Path to the XML file that will contain the sheet data */
     protected $worksheetFilePath;
 
-    /** @var \Box\Spout\Writer\Helper\XLSX\SharedStringsHelper Helper to write shared strings */
+    /** @var \Box\Spout\Writer\XLSX\Helper\SharedStringsHelper Helper to write shared strings */
     protected $sharedStringsHelper;
 
     /** @var bool Whether inline or shared strings should be used */
@@ -42,9 +42,9 @@ EOD;
     protected $lastWrittenRowIndex = 0;
 
     /**
-     * @param \Box\Spout\Writer\Sheet $externalSheet The associated "external" sheet
+     * @param \Box\Spout\Writer\XLSX\Sheet $externalSheet The associated "external" sheet
      * @param string $worksheetFilesFolder Temporary folder where the files to create the XLSX will be stored
-     * @param \Box\Spout\Writer\Helper\XLSX\SharedStringsHelper $sharedStringsHelper Helper for shared strings
+     * @param \Box\Spout\Writer\XLSX\Helper\SharedStringsHelper $sharedStringsHelper Helper for shared strings
      * @param bool $shouldUseInlineStrings Whether inline or shared strings should be used
      * @throws \Box\Spout\Common\Exception\IOException If the sheet data file cannot be opened for writing
      */
@@ -56,7 +56,7 @@ EOD;
 
         $this->stringsEscaper = new \Box\Spout\Common\Escaper\XLSX();
 
-        $this->worksheetFilePath = $worksheetFilesFolder . DIRECTORY_SEPARATOR . strtolower($this->externalSheet->getName()) . '.xml';
+        $this->worksheetFilePath = $worksheetFilesFolder . '/' . strtolower($this->externalSheet->getName()) . '.xml';
         $this->startSheet();
     }
 
@@ -76,7 +76,7 @@ EOD;
     }
 
     /**
-     * @return \Box\Spout\Writer\Sheet The "external" sheet
+     * @return \Box\Spout\Writer\XLSX\Sheet The "external" sheet
      */
     public function getExternalSheet()
     {
@@ -156,7 +156,7 @@ EOD;
 
         $wasWriteSuccessful = fwrite($this->sheetFilePointer, $data);
         if ($wasWriteSuccessful === false) {
-            throw new IOException('Unable to write data in ' . $this->worksheetFilePath);
+            throw new IOException("Unable to write data in {$this->worksheetFilePath}");
         }
 
         // only update the count if the write worked

src/Spout/Writer/XLSX/Sheet.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace Box\Spout\Writer;
+namespace Box\Spout\Writer\XLSX;
 
 /**
  * Class Sheet
  * Represents a worksheet within a XLSX file
  *
- * @package Box\Spout\Writer
+ * @package Box\Spout\Writer\XLSX
  */
 class Sheet
 {
@@ -21,7 +21,7 @@ class Sheet
     /**
      * @param int $sheetIndex Index of the sheet, based on order of creation (zero-based)
      */
-    function __construct($sheetIndex)
+    public function __construct($sheetIndex)
     {
         $this->index = $sheetIndex;
         $this->name = self::DEFAULT_SHEET_NAME_PREFIX . ($sheetIndex + 1);
@@ -45,7 +45,7 @@ class Sheet
 
     /**
      * @param string $name Name of the sheet
-     * @return \Box\Spout\Writer\Sheet
+     * @return Sheet
      */
     public function setName($name)
     {

src/Spout/Writer/XLSX/Writer.php

@@ -1,17 +1,18 @@
 <?php
 
-namespace Box\Spout\Writer;
+namespace Box\Spout\Writer\XLSX;
 
+use Box\Spout\Writer\AbstractWriter;
 use Box\Spout\Writer\Exception\WriterNotOpenedException;
-use Box\Spout\Writer\Internal\XLSX\Workbook;
+use Box\Spout\Writer\XLSX\Internal\Workbook;
 
 /**
- * Class XLSX
+ * Class Writer
  * This class provides base support to write data to XLSX files
  *
- * @package Box\Spout\Writer
+ * @package Box\Spout\Writer\XLSX
  */
-class XLSX extends AbstractWriter
+class Writer extends AbstractWriter
 {
     /** @var string Content-Type value for the header */
     protected static $headerContentType = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
@@ -25,7 +26,7 @@ class XLSX extends AbstractWriter
     /** @var bool Whether new sheets should be automatically created when the max rows limit per sheet is reached */
     protected $shouldCreateNewSheetsAutomatically = true;
 
-    /** @var Internal\XLSX\Workbook The workbook for the XLSX file */
+    /** @var Internal\Workbook The workbook for the XLSX file */
     protected $book;
 
     /** @var int */
@@ -33,7 +34,7 @@ class XLSX extends AbstractWriter
 
     /**
      * @param string $tempFolder Temporary folder where the files to create the XLSX will be stored
-     * @return XLSX
+     * @return Writer
      */
     public function setTempFolder($tempFolder)
     {
@@ -45,7 +46,7 @@ class XLSX extends AbstractWriter
      * Use inline string to be more memory efficient. If set to false, it will use shared strings.
      *
      * @param bool $shouldUseInlineStrings Whether inline or shared strings should be used
-     * @return XLSX
+     * @return Writer
      */
     public function setShouldUseInlineStrings($shouldUseInlineStrings)
     {
@@ -55,7 +56,7 @@ class XLSX extends AbstractWriter
 
     /**
      * @param bool $shouldCreateNewSheetsAutomatically Whether new sheets should be automatically created when the max rows limit per sheet is reached
-     * @return XLSX
+     * @return Writer
      */
     public function setShouldCreateNewSheetsAutomatically($shouldCreateNewSheetsAutomatically)
     {
@@ -91,7 +92,7 @@ class XLSX extends AbstractWriter
         $externalSheets = [];
         $worksheets = $this->book->getWorksheets();
 
-        /** @var Internal\XLSX\Worksheet $worksheet */
+        /** @var Internal\Worksheet $worksheet */
         foreach ($worksheets as $worksheet) {
             $externalSheets[] = $worksheet->getExternalSheet();
         }

tests/Spout/Common/Helper/EncodingHelperTest.php

@@ -0,0 +1,223 @@
+<?php
+
+namespace Box\Spout\Common\Helper;
+
+use Box\Spout\TestUsingResource;
+
+/**
+ * Class EncodingHelperTest
+ *
+ * @package Box\Spout\Common\Helper
+ */
+class EncodingHelperTest extends \PHPUnit_Framework_TestCase
+{
+    use TestUsingResource;
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestGetBytesOffsetToSkipBOM()
+    {
+        return [
+            ['csv_with_utf8_bom.csv', EncodingHelper::ENCODING_UTF8, 3],
+            ['csv_with_utf16be_bom.csv', EncodingHelper::ENCODING_UTF16_BE, 2],
+            ['csv_with_utf32le_bom.csv', EncodingHelper::ENCODING_UTF32_LE, 4],
+            ['csv_with_encoding_utf16le_no_bom.csv', EncodingHelper::ENCODING_UTF16_LE, 0],
+            ['csv_standard.csv', EncodingHelper::ENCODING_UTF8, 0],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestGetBytesOffsetToSkipBOM
+     *
+     * @param string $fileName
+     * @param string $encoding
+     * @param int $expectedBytesOffset
+     * @return void
+     */
+    public function testGetBytesOffsetToSkipBOM($fileName, $encoding, $expectedBytesOffset)
+    {
+        $resourcePath = $this->getResourcePath($fileName);
+        $filePointer = fopen($resourcePath, 'r');
+
+        $encodingHelper = new EncodingHelper(new GlobalFunctionsHelper());
+        $bytesOffset = $encodingHelper->getBytesOffsetToSkipBOM($filePointer, $encoding);
+
+        $this->assertEquals($expectedBytesOffset, $bytesOffset);
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForIconvOrMbstringUsage()
+    {
+        return [
+            [$shouldUseIconv = true],
+            [$shouldNotUseIconv = false],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForIconvOrMbstringUsage
+     * @expectedException \Box\Spout\Common\Exception\EncodingConversionException
+     *
+     * @param bool $shouldUseIconv
+     * @return void
+     */
+    public function testAttemptConversionToUTF8ShouldThrowIfConversionFailed($shouldUseIconv)
+    {
+        $helperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\GlobalFunctionsHelper')
+                        ->setMethods(['iconv', 'mb_convert_encoding'])
+                        ->getMock();
+        $helperStub->method('iconv')->willReturn(false);
+        $helperStub->method('mb_convert_encoding')->willReturn(false);
+
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->setConstructorArgs([$helperStub])
+                        ->setMethods(['canUseIconv', 'canUseMbString'])
+                        ->getMock();
+        $encodingHelperStub->method('canUseIconv')->willReturn($shouldUseIconv);
+        $encodingHelperStub->method('canUseMbString')->willReturn(true);
+
+        $encodingHelperStub->attemptConversionToUTF8('input', EncodingHelper::ENCODING_UTF16_LE);
+    }
+
+    /**
+     * @expectedException \Box\Spout\Common\Exception\EncodingConversionException
+     *
+     * @return void
+     */
+    public function testAttemptConversionToUTF8ShouldThrowIfConversionNotSupported()
+    {
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->disableOriginalConstructor()
+                        ->setMethods(['canUseIconv', 'canUseMbString'])
+                        ->getMock();
+        $encodingHelperStub->method('canUseIconv')->willReturn(false);
+        $encodingHelperStub->method('canUseMbString')->willReturn(false);
+
+        $encodingHelperStub->attemptConversionToUTF8('input', EncodingHelper::ENCODING_UTF16_LE);
+    }
+
+    /**
+     * @dataProvider dataProviderForIconvOrMbstringUsage
+     *
+     * @param bool $shouldUseIconv
+     * @return void
+     */
+    public function testAttemptConversionToUTF8ShouldReturnReencodedString($shouldUseIconv)
+    {
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->setConstructorArgs([new GlobalFunctionsHelper()])
+                        ->setMethods(['canUseIconv', 'canUseMbString'])
+                        ->getMock();
+        $encodingHelperStub->method('canUseIconv')->willReturn($shouldUseIconv);
+        $encodingHelperStub->method('canUseMbString')->willReturn(true);
+
+        $encodedString = iconv(EncodingHelper::ENCODING_UTF8, EncodingHelper::ENCODING_UTF16_LE, 'input');
+        $decodedString = $encodingHelperStub->attemptConversionToUTF8($encodedString, EncodingHelper::ENCODING_UTF16_LE);
+
+        $this->assertEquals('input', $decodedString);
+    }
+
+    /**
+     * @return void
+     */
+    public function testAttemptConversionToUTF8ShouldBeNoopWhenTargetIsUTF8()
+    {
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->disableOriginalConstructor()
+                        ->setMethods(['canUseIconv'])
+                        ->getMock();
+        $encodingHelperStub->expects($this->never())->method('canUseIconv');
+
+        $decodedString = $encodingHelperStub->attemptConversionToUTF8('input', EncodingHelper::ENCODING_UTF8);
+        $this->assertEquals('input', $decodedString);
+    }
+
+    /**
+     * @dataProvider dataProviderForIconvOrMbstringUsage
+     * @expectedException \Box\Spout\Common\Exception\EncodingConversionException
+     *
+     * @param bool $shouldUseIconv
+     * @return void
+     */
+    public function testAttemptConversionFromUTF8ShouldThrowIfConversionFailed($shouldUseIconv)
+    {
+        $helperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\GlobalFunctionsHelper')
+                        ->setMethods(['iconv', 'mb_convert_encoding'])
+                        ->getMock();
+        $helperStub->method('iconv')->willReturn(false);
+        $helperStub->method('mb_convert_encoding')->willReturn(false);
+
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->setConstructorArgs([$helperStub])
+                        ->setMethods(['canUseIconv', 'canUseMbString'])
+                        ->getMock();
+        $encodingHelperStub->method('canUseIconv')->willReturn($shouldUseIconv);
+        $encodingHelperStub->method('canUseMbString')->willReturn(true);
+
+        $encodingHelperStub->attemptConversionFromUTF8('input', EncodingHelper::ENCODING_UTF16_LE);
+    }
+
+    /**
+     * @expectedException \Box\Spout\Common\Exception\EncodingConversionException
+     *
+     * @return void
+     */
+    public function testAttemptConversionFromUTF8ShouldThrowIfConversionNotSupported()
+    {
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->disableOriginalConstructor()
+                        ->setMethods(['canUseIconv', 'canUseMbString'])
+                        ->getMock();
+        $encodingHelperStub->method('canUseIconv')->willReturn(false);
+        $encodingHelperStub->method('canUseMbString')->willReturn(false);
+
+        $encodingHelperStub->attemptConversionFromUTF8('input', EncodingHelper::ENCODING_UTF16_LE);
+    }
+
+    /**
+     * @dataProvider dataProviderForIconvOrMbstringUsage
+     *
+     * @param bool $shouldUseIconv
+     * @return void
+     */
+    public function testAttemptConversionFromUTF8ShouldReturnReencodedString($shouldUseIconv)
+    {
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->setConstructorArgs([new GlobalFunctionsHelper()])
+                        ->setMethods(['canUseIconv', 'canUseMbString'])
+                        ->getMock();
+        $encodingHelperStub->method('canUseIconv')->willReturn($shouldUseIconv);
+        $encodingHelperStub->method('canUseMbString')->willReturn(true);
+
+        $encodedString = $encodingHelperStub->attemptConversionFromUTF8('input', EncodingHelper::ENCODING_UTF16_LE);
+        $encodedStringWithIconv = iconv(EncodingHelper::ENCODING_UTF8, EncodingHelper::ENCODING_UTF16_LE, 'input');
+
+        $this->assertEquals($encodedStringWithIconv, $encodedString);
+    }
+
+    /**
+     * @return void
+     */
+    public function testAttemptConversionFromUTF8ShouldBeNoopWhenTargetIsUTF8()
+    {
+        /** @var EncodingHelper $encodingHelperStub */
+        $encodingHelperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\EncodingHelper')
+                        ->disableOriginalConstructor()
+                        ->setMethods(['canUseIconv'])
+                        ->getMock();
+        $encodingHelperStub->expects($this->never())->method('canUseIconv');
+
+        $encodedString = $encodingHelperStub->attemptConversionFromUTF8('input', EncodingHelper::ENCODING_UTF8);
+        $this->assertEquals('input', $encodedString);
+    }
+}

tests/Spout/Reader/CSV/ReaderTest.php

@@ -0,0 +1,357 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\ReaderFactory;
+use Box\Spout\Common\Type;
+use Box\Spout\Common\Helper\EncodingHelper;
+use Box\Spout\TestUsingResource;
+
+/**
+ * Class ReaderTest
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class ReaderTest extends \PHPUnit_Framework_TestCase
+{
+    use TestUsingResource;
+
+    /**
+     * @expectedException \Box\Spout\Common\Exception\IOException
+     *
+     * @return void
+     */
+    public function testOpenShouldThrowExceptionIfFileDoesNotExist()
+    {
+        ReaderFactory::create(Type::CSV)->open('/path/to/fake/file.csv');
+    }
+
+    /**
+     * @expectedException \Box\Spout\Reader\Exception\ReaderNotOpenedException
+     *
+     * @return void
+     */
+    public function testOpenShouldThrowExceptionIfTryingToReadBeforeOpeningReader()
+    {
+        ReaderFactory::create(Type::CSV)->getSheetIterator();
+    }
+
+    /**
+     * @expectedException \Box\Spout\Common\Exception\IOException
+     *
+     * @return void
+     */
+    public function testOpenShouldThrowExceptionIfFileNotReadable()
+    {
+        $helperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\GlobalFunctionsHelper')
+                        ->setMethods(['is_readable'])
+                        ->getMock();
+        $helperStub->method('is_readable')->willReturn(false);
+
+        $resourcePath = $this->getResourcePath('csv_standard.csv');
+
+        $reader = ReaderFactory::create(Type::CSV);
+        $reader->setGlobalFunctionsHelper($helperStub);
+        $reader->open($resourcePath);
+    }
+
+    /**
+     * @expectedException \Box\Spout\Common\Exception\IOException
+     *
+     * @return void
+     */
+    public function testOpenShouldThrowExceptionIfCannotOpenFile()
+    {
+        $helperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\GlobalFunctionsHelper')
+                        ->setMethods(['fopen'])
+                        ->getMock();
+        $helperStub->method('fopen')->willReturn(false);
+
+        $resourcePath = $this->getResourcePath('csv_standard.csv');
+
+        $reader = ReaderFactory::create(Type::CSV);
+        $reader->setGlobalFunctionsHelper($helperStub);
+        $reader->open($resourcePath);
+    }
+
+
+    /**
+     * @return void
+     */
+    public function testReadStandardCSV()
+    {
+        $allRows = $this->getAllRowsForFile('csv_standard.csv');
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--21', 'csv--22', 'csv--23'],
+            ['csv--31', 'csv--32', 'csv--33'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return void
+     */
+    public function testReadShouldNotStopAtCommaIfEnclosed()
+    {
+        $allRows = $this->getAllRowsForFile('csv_with_comma_enclosed.csv');
+        $this->assertEquals('This is, a comma', $allRows[0][0]);
+    }
+
+    /**
+     * @return void
+     */
+    public function testReadShouldKeepEmptyCells()
+    {
+        $allRows = $this->getAllRowsForFile('csv_with_empty_cells.csv');
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--21', '', 'csv--23'],
+            ['csv--31', 'csv--32', ''],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestReadShouldSkipEmptyLines()
+    {
+        return [
+            ['csv_with_empty_line.csv'],
+            ['csv_with_empty_last_line.csv'],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestReadShouldSkipEmptyLines
+     *
+     * @param string $fileName
+     * @return void
+     */
+    public function testReadShouldSkipEmptyLines($fileName)
+    {
+        $allRows = $this->getAllRowsForFile($fileName);
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--31', 'csv--32', 'csv--33'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return void
+     */
+    public function testReadShouldHaveTheRightNumberOfCells()
+    {
+        $allRows = $this->getAllRowsForFile('csv_with_different_cells_number.csv');
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--21', 'csv--22'],
+            ['csv--31'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return void
+     */
+    public function testReadShouldSupportCustomFieldDelimiter()
+    {
+        $allRows = $this->getAllRowsForFile('csv_delimited_with_pipes.csv', '|');
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--21', 'csv--22', 'csv--23'],
+            ['csv--31', 'csv--32', 'csv--33'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return void
+     */
+    public function testReadShouldSupportCustomFieldEnclosure()
+    {
+        $allRows = $this->getAllRowsForFile('csv_text_enclosed_with_pound.csv', ',', '#');
+        $this->assertEquals('This is, a comma', $allRows[0][0]);
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestReadShouldSkipBom()
+    {
+        return [
+            ['csv_with_utf8_bom.csv', EncodingHelper::ENCODING_UTF8],
+            ['csv_with_utf16le_bom.csv', EncodingHelper::ENCODING_UTF16_LE],
+            ['csv_with_utf16be_bom.csv', EncodingHelper::ENCODING_UTF16_BE],
+            ['csv_with_utf32le_bom.csv', EncodingHelper::ENCODING_UTF32_LE],
+            ['csv_with_utf32be_bom.csv', EncodingHelper::ENCODING_UTF32_BE],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestReadShouldSkipBom
+     *
+     * @param string $fileName
+     * @param string $fileEncoding
+     * @return void
+     */
+    public function testReadShouldSkipBom($fileName, $fileEncoding)
+    {
+        $allRows = $this->getAllRowsForFile($fileName, ',', '"', $fileEncoding);
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--21', 'csv--22', 'csv--23'],
+            ['csv--31', 'csv--32', 'csv--33'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestReadShouldSupportNonUTF8FilesWithoutBOMs()
+    {
+        $shouldUseIconv = true;
+        $shouldNotUseIconv = false;
+
+        return [
+            ['csv_with_encoding_utf16le_no_bom.csv', EncodingHelper::ENCODING_UTF16_LE, $shouldUseIconv],
+            ['csv_with_encoding_utf16le_no_bom.csv', EncodingHelper::ENCODING_UTF16_LE, $shouldNotUseIconv],
+            ['csv_with_encoding_cp1252.csv', 'CP1252', $shouldUseIconv],
+            ['csv_with_encoding_cp1252.csv', 'CP1252', $shouldNotUseIconv],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestReadShouldSupportNonUTF8FilesWithoutBOMs
+     *
+     * @param string $fileName
+     * @param string $fileEncoding
+     * @param bool $shouldUseIconv
+     * @return void
+     */
+    public function testReadShouldSupportNonUTF8FilesWithoutBOMs($fileName, $fileEncoding, $shouldUseIconv)
+    {
+        $allRows = [];
+        $resourcePath = $this->getResourcePath($fileName);
+
+        $helperStub = $this->getMockBuilder('\Box\Spout\Common\Helper\GlobalFunctionsHelper')
+                        ->setMethods(['function_exists'])
+                        ->getMock();
+
+        $returnValueMap = [
+            ['iconv', $shouldUseIconv],
+            ['mb_convert_encoding', true],
+        ];
+        $helperStub->method('function_exists')->will($this->returnValueMap($returnValueMap));
+
+        /** @var \Box\Spout\Reader\CSV\Reader $reader */
+        $reader = ReaderFactory::create(Type::CSV);
+        $reader
+            ->setGlobalFunctionsHelper($helperStub)
+            ->setEncoding($fileEncoding)
+            ->open($resourcePath);
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+            }
+        }
+
+        $reader->close();
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--21', 'csv--22', 'csv--23'],
+            ['csv--31', 'csv--32', 'csv--33'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @return void
+     */
+    public function testReadMultipleTimesShouldRewindReader()
+    {
+        $allRows = [];
+        $resourcePath = $this->getResourcePath('csv_standard.csv');
+
+        $reader = ReaderFactory::create(Type::CSV);
+        $reader->open($resourcePath);
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            // do nothing
+        }
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+                break;
+            }
+
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+                break;
+            }
+        }
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+                break;
+            }
+        }
+
+        $reader->close();
+
+        $expectedRows = [
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--11', 'csv--12', 'csv--13'],
+            ['csv--11', 'csv--12', 'csv--13'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
+    /**
+     * @param string $fileName
+     * @param string|void $fieldDelimiter
+     * @param string|void $fieldEnclosure
+     * @param string|void $encoding
+     * @return array All the read rows the given file
+     */
+    private function getAllRowsForFile(
+        $fileName,
+        $fieldDelimiter = ',',
+        $fieldEnclosure = '"',
+        $encoding = EncodingHelper::ENCODING_UTF8)
+    {
+        $allRows = [];
+        $resourcePath = $this->getResourcePath($fileName);
+
+        /** @var \Box\Spout\Reader\CSV\Reader $reader */
+        $reader = ReaderFactory::create(Type::CSV);
+        $reader
+            ->setFieldDelimiter($fieldDelimiter)
+            ->setFieldEnclosure($fieldEnclosure)
+            ->setEncoding($encoding)
+            ->open($resourcePath);
+
+        foreach ($reader->getSheetIterator() as $sheetIndex => $sheet) {
+            foreach ($sheet->getRowIterator() as $rowIndex => $row) {
+                $allRows[] = $row;
+            }
+        }
+
+        $reader->close();
+
+        return $allRows;
+    }
+}

tests/Spout/Reader/CSVTest.php

@@ -1,158 +0,0 @@
-<?php
-
-namespace Box\Spout\Reader;
-
-use Box\Spout\Common\Type;
-use Box\Spout\TestUsingResource;
-
-/**
- * Class CSVTest
- *
- * @package Box\Spout\Reader
- */
-class CSVTest extends \PHPUnit_Framework_TestCase
-{
-    use TestUsingResource;
-
-    /**
-     * @expectedException \Box\Spout\Common\Exception\IOException
-     *
-     * @return void
-     */
-    public function testReadShouldThrowExceptionIfFileDoesNotExist()
-    {
-        $this->getAllRowsForFile('/path/to/fake/file.csv');
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadStandardCSV()
-    {
-        $allRows = $this->getAllRowsForFile('csv_standard.csv');
-
-        $expectedRows = [
-            ['csv--11', 'csv--12', 'csv--13'],
-            ['csv--21', 'csv--22', 'csv--23'],
-            ['csv--31', 'csv--32', 'csv--33'],
-        ];
-        $this->assertEquals($expectedRows, $allRows);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldNotStopAtCommaIfEnclosed()
-    {
-        $allRows = $this->getAllRowsForFile('csv_with_comma_enclosed.csv');
-        $this->assertEquals('This is, a comma', $allRows[0][0]);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldKeepEmptyCells()
-    {
-        $allRows = $this->getAllRowsForFile('csv_with_empty_cells.csv');
-
-        $expectedRows = [
-            ['csv--11', 'csv--12', 'csv--13'],
-            ['csv--21', '', 'csv--23'],
-            ['csv--31', 'csv--32', ''],
-        ];
-        $this->assertEquals($expectedRows, $allRows);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldSkipEmptyLines()
-    {
-        $allRows = $this->getAllRowsForFile('csv_with_empty_line.csv');
-
-        $expectedRows = [
-            ['csv--11', 'csv--12', 'csv--13'],
-            ['csv--31', 'csv--32', 'csv--33'],
-        ];
-        $this->assertEquals($expectedRows, $allRows);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldHaveTheRightNumberOfCells()
-    {
-        $allRows = $this->getAllRowsForFile('csv_with_different_cells_number.csv');
-
-        $expectedRows = [
-            ['csv--11', 'csv--12', 'csv--13'],
-            ['csv--21', 'csv--22'],
-            ['csv--31'],
-        ];
-        $this->assertEquals($expectedRows, $allRows);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldSupportCustomFieldDelimiter()
-    {
-        $allRows = $this->getAllRowsForFile('csv_delimited_with_pipes.csv', '|');
-
-        $expectedRows = [
-            ['csv--11', 'csv--12', 'csv--13'],
-            ['csv--21', 'csv--22', 'csv--23'],
-            ['csv--31', 'csv--32', 'csv--33'],
-        ];
-        $this->assertEquals($expectedRows, $allRows);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldSupportCustomFieldEnclosure()
-    {
-        $allRows = $this->getAllRowsForFile('csv_text_enclosed_with_pound.csv', ',', '#');
-        $this->assertEquals('This is, a comma', $allRows[0][0]);
-    }
-
-    /**
-     * @return void
-     */
-    public function testReadShouldSkipUtf8Bom()
-    {
-        $allRows = $this->getAllRowsForFile('csv_with_utf8_bom.csv');
-
-        $expectedRows = [
-            ['csv--11', 'csv--12', 'csv--13'],
-            ['csv--21', 'csv--22', 'csv--23'],
-        ];
-        $this->assertEquals($expectedRows, $allRows);
-    }
-
-    /**
-     * @param string $fileName
-     * @param string|void $fieldDelimiter
-     * @param string|void $fieldEnclosure
-     * @return array All the read rows the given file
-     */
-    private function getAllRowsForFile($fileName, $fieldDelimiter = ",", $fieldEnclosure = '"')
-    {
-        $allRows = [];
-        $resourcePath = $this->getResourcePath($fileName);
-
-        $reader = ReaderFactory::create(Type::CSV);
-        $reader->setFieldDelimiter($fieldDelimiter);
-        $reader->setFieldEnclosure($fieldEnclosure);
-
-        $reader->open($resourcePath);
-
-        while ($reader->hasNextRow()) {
-            $allRows[] = $reader->nextRow();
-        }
-
-        $reader->close();
-
-        return $allRows;
-    }
-}

tests/Spout/Reader/Wrapper/SimpleXMLElementTest.php

@@ -0,0 +1,127 @@
+<?php
+
+namespace Box\Spout\Reader\Wrapper;
+
+use Box\Spout\TestUsingResource;
+
+/**
+ * Class SimpleXMLElementTest
+ *
+ * @package Box\Spout\Reader\Wrapper
+ */
+class SimpleXMLElementTest extends \PHPUnit_Framework_TestCase
+{
+    use TestUsingResource;
+
+    /**
+     * @expectedException \Box\Spout\Reader\Exception\XMLProcessingException
+     *
+     * @return void
+     */
+    public function testConstructShouldThrowExceptionIfInvalidData()
+    {
+        $invalidXML = '<invalid><xml></invalid>';
+        new SimpleXMLElement($invalidXML);
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestGetAttribute()
+    {
+        $xmlWithoutNamespace = <<<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<worksheet foo="bar" type="test" />
+XML;
+
+        $xmlWithHalfNamespace = <<<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<worksheet
+    xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+    foo="bar" r:type="test" />
+XML;
+
+        $xmlWithFullNamespace = <<<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<worksheet
+    xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+    r:foo="bar" r:type="test" />
+XML;
+
+        return [
+            [$xmlWithoutNamespace, null, ['foo' => 'bar', 'type' => 'test']],
+            [$xmlWithHalfNamespace, null, ['foo' => 'bar', 'type' => null]],
+            [$xmlWithFullNamespace, null, ['foo' => null, 'type' => null]],
+            [$xmlWithoutNamespace, 'r', ['foo' => null, 'type' => null]],
+            [$xmlWithHalfNamespace, 'r', ['foo' => null, 'type' => 'test']],
+            [$xmlWithFullNamespace, 'r', ['foo' => 'bar', 'type' => 'test']],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestGetAttribute
+     *
+     * @param string $xml
+     * @param string|null $namespace
+     * @param array $expectedAttributes
+     * @return void
+     */
+    public function testGetAttribute($xml, $namespace, $expectedAttributes)
+    {
+        $element = new SimpleXMLElement($xml);
+
+        foreach ($expectedAttributes as $name => $expectedValue) {
+            $value = $element->getAttribute($name, $namespace);
+            $this->assertEquals($expectedValue, $value);
+        }
+    }
+
+    /**
+     * @return void
+     */
+    public function testXPath()
+    {
+        $xml = <<<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<worksheet>
+    <sheetData>
+        <row r="1">
+            <c r="A1"><v>0</v></c>
+            <c r="A2"><v>1</v></c>
+        </row>
+    </sheetData>
+</worksheet>
+XML;
+
+        $element = new SimpleXMLElement($xml);
+        $matchedElements = $element->xpath('//c');
+
+        $this->assertEquals(2, count($matchedElements));
+        $this->assertTrue($matchedElements[0] instanceof SimpleXMLElement, 'The SimpleXMLElement should be wrapped');
+        $this->assertEquals('A2', $matchedElements[1]->getAttribute('r'));
+    }
+
+    /**
+     * @return void
+     */
+    public function testRemoveNodeMatchingXPath()
+    {
+        $xml = <<<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<worksheet>
+    <sheetData>
+        <row r="1">
+            <c r="A1"><v>0</v></c>
+            <c r="A2"><v>1</v></c>
+        </row>
+    </sheetData>
+</worksheet>
+XML;
+
+        $element = new SimpleXMLElement($xml);
+        $this->assertNotNull($element->getFirstChildByTagName('sheetData'));
+
+        $element->removeNodesMatchingXPath('//sheetData');
+        $this->assertNull($element->getFirstChildByTagName('sheetData'));
+    }
+}

tests/Spout/Reader/Wrapper/XMLReaderTest.php

@@ -0,0 +1,166 @@
+<?php
+
+namespace Box\Spout\Reader\Wrapper;
+
+use Box\Spout\TestUsingResource;
+use Box\Spout\Reader\Exception\XMLProcessingException;
+
+/**
+ * Class XMLReaderTest
+ *
+ * @package Box\Spout\Reader\Wrapper
+ */
+class XMLReaderTest extends \PHPUnit_Framework_TestCase
+{
+    use TestUsingResource;
+
+    /**
+     * @return void
+     */
+    public function testOpenShouldFailIfFileInsideZipDoesNotExist()
+    {
+        $resourcePath = $this->getResourcePath('one_sheet_with_inline_strings.xlsx');
+        $nonExistingXMLFilePath = 'zip://' . $resourcePath . '#path/to/fake/file.xml';
+
+        $xmlReader = new XMLReader();
+
+        // using "@" to prevent errors/warning to be displayed
+        $wasOpenSuccessful = @$xmlReader->open($nonExistingXMLFilePath);
+
+        $this->assertTrue($wasOpenSuccessful === false);
+    }
+
+    /**
+     * Testing a HHVM bug: https://github.com/facebook/hhvm/issues/5779
+     * The associated code in XMLReader::open() can be removed when the issue is fixed (and this test starts failing).
+     * @see XMLReader::open()
+     *
+     * @return void
+     */
+    public function testHHVMStillDoesNotComplainWhenCallingOpenWithFileInsideZipNotExisting()
+    {
+        // Test should only be run on HHVM
+        if ($this->isRunningHHVM()) {
+            $resourcePath = $this->getResourcePath('one_sheet_with_inline_strings.xlsx');
+            $nonExistingXMLFilePath = 'zip://' . $resourcePath . '#path/to/fake/file.xml';
+
+            libxml_clear_errors();
+            $initialUseInternalErrorsSetting = libxml_use_internal_errors(true);
+
+            // using the built-in XMLReader
+            $xmlReader = new \XMLReader();
+            $this->assertTrue($xmlReader->open($nonExistingXMLFilePath) !== false);
+            $this->assertTrue(libxml_get_last_error() === false);
+
+            libxml_use_internal_errors($initialUseInternalErrorsSetting);
+        }
+    }
+
+    /**
+     * @return bool TRUE if running on HHVM, FALSE otherwise
+     */
+    private function isRunningHHVM()
+    {
+        return defined('HHVM_VERSION');
+    }
+
+    /**
+     * @expectedException \Box\Spout\Reader\Exception\XMLProcessingException
+     *
+     * @return void
+     */
+    public function testReadShouldThrowExceptionOnError()
+    {
+        $resourcePath = $this->getResourcePath('one_sheet_with_invalid_xml_characters.xlsx');
+        $sheetDataXMLFilePath = 'zip://' . $resourcePath . '#xl/worksheets/sheet1.xml';
+
+        $xmlReader = new XMLReader();
+        if ($xmlReader->open($sheetDataXMLFilePath) === false) {
+            $this->fail();
+        }
+
+        // using "@" to prevent errors/warning to be displayed
+        while (@$xmlReader->read()) {
+            // do nothing
+        }
+    }
+
+    /**
+     * @expectedException \Box\Spout\Reader\Exception\XMLProcessingException
+     *
+     * @return void
+     */
+    public function testNextShouldThrowExceptionOnError()
+    {
+        // The sharedStrings.xml file in "attack_billion_laughs.xlsx" contains
+        // a doctype element that causes read errors
+        $resourcePath = $this->getResourcePath('attack_billion_laughs.xlsx');
+        $sheetDataXMLFilePath = 'zip://' . $resourcePath . '#xl/sharedStrings.xml';
+
+        $xmlReader = new XMLReader();
+        if ($xmlReader->open($sheetDataXMLFilePath) !== false) {
+            @$xmlReader->next('sst');
+        }
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestIsZipStream()
+    {
+        return [
+            ['/absolute/path/to/file.xlsx', false],
+            ['relative/path/to/file.xlsx', false],
+            ['php://temp', false],
+            ['zip:///absolute/path/to/file.xlsx', true],
+            ['zip://relative/path/to/file.xlsx', true],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestIsZipStream
+     *
+     * @param string $URI
+     * @param bool $expectedResult
+     * @return void
+     */
+    public function testIsZipStream($URI, $expectedResult)
+    {
+        $xmlReader = new XMLReader();
+        $isZipStream = \ReflectionHelper::callMethodOnObject($xmlReader, 'isZipStream', $URI);
+
+        $this->assertEquals($expectedResult, $isZipStream);
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestFileExistsWithinZip()
+    {
+        return [
+            ['[Content_Types].xml', true],
+            ['xl/sharedStrings.xml', true],
+            ['xl/worksheets/sheet1.xml', true],
+            ['/invalid/file.xml', false],
+            ['another/invalid/file.xml', false],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestFileExistsWithinZip
+     *
+     * @param string $innerFilePath
+     * @param bool $expectedResult
+     * @return void
+     */
+    public function testFileExistsWithinZip($innerFilePath, $expectedResult)
+    {
+        $resourcePath = $this->getResourcePath('one_sheet_with_inline_strings.xlsx');
+        $zipStreamURI = 'zip://' . $resourcePath . '#' . $innerFilePath;
+
+        $xmlReader = new XMLReader();
+        $isZipStream = \ReflectionHelper::callMethodOnObject($xmlReader, 'fileExistsWithinZip', $zipStreamURI);
+
+        $this->assertEquals($expectedResult, $isZipStream);
+    }
+}

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

@@ -1,11 +1,11 @@
 <?php
 
-namespace Box\Spout\Reader\Helper\XLSX;
+namespace Box\Spout\Reader\XLSX\Helper;
 
 /**
  * Class CellHelperTest
  *
- * @package Box\Spout\Reader\Helper\XLSX
+ * @package Box\Spout\Reader\XLSX\Helper
  */
 class CellHelperTest extends \PHPUnit_Framework_TestCase
 {

tests/Spout/Reader/XLSX/Helper/SharedStringsCaching/CachingStrategyFactoryTest.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace Box\Spout\Reader\XLSX\Helper\SharedStringsCaching;
+
+/**
+ * Class CachingStrategyFactoryTest
+ *
+ * @package Box\Spout\Reader\XLSX\Helper\SharedStringsCaching
+ */
+class CachingStrategyFactoryTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @return array
+     */
+    public function dataProviderForTestGetBestCachingStrategy()
+    {
+        return [
+            [CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE, -1, 'FileBasedStrategy'],
+            [CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE + 10, -1, 'FileBasedStrategy'],
+            [CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE - 10, -1, 'InMemoryStrategy'],
+            [10 , CachingStrategyFactory::AMOUNT_MEMORY_NEEDED_PER_STRING_IN_KB * 10, 'FileBasedStrategy'],
+            [15, CachingStrategyFactory::AMOUNT_MEMORY_NEEDED_PER_STRING_IN_KB * 10, 'FileBasedStrategy'],
+            [5 , CachingStrategyFactory::AMOUNT_MEMORY_NEEDED_PER_STRING_IN_KB * 10, 'InMemoryStrategy'],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestGetBestCachingStrategy
+     *
+     * @param int $sharedStringsUniqueCount
+     * @param int $memoryLimitInKB
+     * @param string $expectedStrategyClassName
+     * @return void
+     */
+    public function testGetBestCachingStrategy($sharedStringsUniqueCount, $memoryLimitInKB, $expectedStrategyClassName)
+    {
+        /** @var CachingStrategyFactory|\PHPUnit_Framework_MockObject_MockObject $factoryStub */
+        $factoryStub = $this
+            ->getMockBuilder('\Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\CachingStrategyFactory')
+            ->disableOriginalConstructor()
+            ->setMethods(['getMemoryLimitInKB'])
+            ->getMock();
+
+        $factoryStub->method('getMemoryLimitInKB')->willReturn($memoryLimitInKB);
+
+        \ReflectionHelper::setStaticValue('\Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\CachingStrategyFactory', 'instance', $factoryStub);
+
+        $strategy = $factoryStub->getBestCachingStrategy($sharedStringsUniqueCount, null);
+
+        $fullExpectedStrategyClassName = 'Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\\' . $expectedStrategyClassName;
+        $this->assertEquals($fullExpectedStrategyClassName, get_class($strategy));
+
+        $strategy->clearCache();
+        \ReflectionHelper::reset();
+    }
+
+    /**
+     * @return array
+     */
+    public function dataProviderForTestGetMemoryLimitInKB()
+    {
+        return [
+            ['-1', -1],
+            ['invalid', -1],
+            ['1024B', 1],
+            ['128K', 128],
+            ['256KB', 256],
+            ['512M', 512 * 1024],
+            ['2MB', 2 * 1024],
+            ['1G', 1 * 1024 * 1024],
+            ['10GB', 10 * 1024 * 1024],
+            ['2T', 2 * 1024 * 1024 * 1024],
+            ['5TB', 5 * 1024 * 1024 * 1024],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestGetMemoryLimitInKB
+     *
+     * @param string $memoryLimitFormatted
+     * @param float $expectedMemoryLimitInKB
+     * @return void
+     */
+    public function testGetMemoryLimitInKB($memoryLimitFormatted, $expectedMemoryLimitInKB)
+    {
+        /** @var CachingStrategyFactory|\PHPUnit_Framework_MockObject_MockObject $factoryStub */
+        $factoryStub = $this
+            ->getMockBuilder('\Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\CachingStrategyFactory')
+            ->disableOriginalConstructor()
+            ->setMethods(['getMemoryLimitFromIni'])
+            ->getMock();
+
+        $factoryStub->method('getMemoryLimitFromIni')->willReturn($memoryLimitFormatted);
+
+        $memoryLimitInKB = \ReflectionHelper::callMethodOnObject($factoryStub, 'getMemoryLimitInKB');
+
+        $this->assertEquals($expectedMemoryLimitInKB, $memoryLimitInKB);
+    }
+}

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

@@ -1,13 +1,16 @@
 <?php
 
-namespace Box\Spout\Reader\Helper\XLSX;
+namespace Box\Spout\Reader\XLSX\Helper;
 
+use Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\CachingStrategyFactory;
+use Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\FileBasedStrategy;
+use Box\Spout\Reader\XLSX\Helper\SharedStringsCaching\InMemoryStrategy;
 use Box\Spout\TestUsingResource;
 
 /**
  * Class SharedStringsHelperTest
  *
- * @package Box\Spout\Reader\Helper\XLSX
+ * @package Box\Spout\Reader\XLSX\Helper
  */
 class SharedStringsHelperTest extends \PHPUnit_Framework_TestCase
 {
@@ -33,46 +36,6 @@ class SharedStringsHelperTest extends \PHPUnit_Framework_TestCase
         $this->sharedStringsHelper->cleanup();
     }
 
-    /**
-     * @return void
-     */
-    public function testExtractSharedStringsShouldCreateTempFileWithSharedStrings()
-    {
-        $this->sharedStringsHelper->extractSharedStrings();
-
-        $tempFolder = \ReflectionHelper::getValueOnObject($this->sharedStringsHelper, 'tempFolder');
-
-        $filesInTempFolder = $this->getFilesInFolder($tempFolder);
-        $this->assertEquals(1, count($filesInTempFolder), 'One temp file should have been created in the temp folder.');
-
-        $tempFileContents = file_get_contents($filesInTempFolder[0]);
-        $tempFileContentsPerLine = explode(PHP_EOL, $tempFileContents);
-
-        $this->assertEquals('s1--A1', $tempFileContentsPerLine[0]);
-        $this->assertEquals('s1--E5', $tempFileContentsPerLine[24]);
-    }
-
-    /**
-     * Returns all files that are in the given folder.
-     * It does not include "." and ".." and is not recursive.
-     *
-     * @param string $folderPath
-     * @return array
-     */
-    private function getFilesInFolder($folderPath)
-    {
-        $files = [];
-        $directoryIterator = new \DirectoryIterator($folderPath);
-
-        foreach ($directoryIterator as $fileInfo) {
-            if ($fileInfo->isFile()) {
-                $files[] = $fileInfo->getPathname();
-            }
-        }
-
-        return $files;
-    }
-
     /**
      * @expectedException \Box\Spout\Reader\Exception\SharedStringNotFoundException
      * @return void
@@ -95,6 +58,9 @@ class SharedStringsHelperTest extends \PHPUnit_Framework_TestCase
 
         $sharedString = $this->sharedStringsHelper->getStringAtIndex(24);
         $this->assertEquals('s1--E5', $sharedString);
+
+        $usedCachingStrategy = \ReflectionHelper::getValueOnObject($this->sharedStringsHelper, 'cachingStrategy');
+        $this->assertTrue($usedCachingStrategy instanceof InMemoryStrategy);
     }
 
     /**
@@ -115,4 +81,32 @@ class SharedStringsHelperTest extends \PHPUnit_Framework_TestCase
 
         $sharedStringsHelper->cleanup();
     }
+
+    /**
+     * @return void
+     */
+    public function testGetStringAtIndexWithFileBasedStrategy()
+    {
+        // force the file-based strategy by setting no memory limit
+        $originalMemoryLimit = ini_get('memory_limit');
+        ini_set('memory_limit', '-1');
+
+        $resourcePath = $this->getResourcePath('sheet_with_lots_of_shared_strings.xlsx');
+        $sharedStringsHelper = new SharedStringsHelper($resourcePath);
+
+        $sharedStringsHelper->extractSharedStrings();
+
+        $sharedString = $sharedStringsHelper->getStringAtIndex(0);
+        $this->assertEquals('str', $sharedString);
+
+        $sharedString = $sharedStringsHelper->getStringAtIndex(CachingStrategyFactory::MAX_NUM_STRINGS_PER_TEMP_FILE + 1);
+        $this->assertEquals('str', $sharedString);
+
+        $usedCachingStrategy = \ReflectionHelper::getValueOnObject($sharedStringsHelper, 'cachingStrategy');
+        $this->assertTrue($usedCachingStrategy instanceof FileBasedStrategy);
+
+        $sharedStringsHelper->cleanup();
+
+        ini_set('memory_limit', $originalMemoryLimit);
+    }
 }

tests/Spout/Reader/XLSX/ReaderTest.php

@@ -1,16 +1,18 @@
 <?php
 
-namespace Box\Spout\Reader;
+namespace Box\Spout\Reader\XLSX;
 
+use Box\Spout\Common\Exception\IOException;
 use Box\Spout\Common\Type;
+use Box\Spout\Reader\ReaderFactory;
 use Box\Spout\TestUsingResource;
 
 /**
- * Class XLSXTest
+ * Class ReaderTest
  *
- * @package Box\Spout\Reader
+ * @package Box\Spout\Reader\XLSX
  */
-class XLSXTest extends \PHPUnit_Framework_TestCase
+class ReaderTest extends \PHPUnit_Framework_TestCase
 {
     use TestUsingResource;
 
@@ -22,6 +24,7 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         return [
             ['/path/to/fake/file.xlsx'],
             ['file_with_no_sheets_in_content_types.xlsx'],
+            ['file_with_sheet_xml_not_matching_content_types.xlsx'],
             ['file_corrupted.xlsx'],
         ];
     }
@@ -35,38 +38,8 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
      */
     public function testReadShouldThrowException($filePath)
     {
-        $this->getAllRowsForFile($filePath);
-    }
-
-    /**
-     * @expectedException \Box\Spout\Reader\Exception\ReaderNotOpenedException
-     *
-     * @return void
-     */
-    public function testHasNextSheetShouldThrowExceptionIfReaderNotOpened()
-    {
-        $reader = ReaderFactory::create(Type::XLSX);
-        $reader->hasNextSheet();
-    }
-
-    /**
-     * @expectedException \Box\Spout\Reader\Exception\EndOfWorksheetsReachedException
-     *
-     * @return void
-     */
-    public function testNextSheetShouldThrowExceptionIfNoMoreSheetsToRead()
-    {
-        $fileName = 'one_sheet_with_shared_strings.xlsx';
-        $resourcePath = $this->getResourcePath($fileName);
-
-        $reader = ReaderFactory::create(Type::XLSX);
-        $reader->open($resourcePath);
-
-        while ($reader->hasNextSheet()) {
-            $reader->nextSheet();
-        }
-
-        $reader->nextSheet();
+        // using @ to prevent warnings/errors from being displayed
+        @$this->getAllRowsForFile($filePath);
     }
 
     /**
@@ -114,6 +87,32 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expectedRows, $allRows);
     }
 
+    /**
+     * @return void
+     */
+    public function testReadShouldSupportAllCellTypes()
+    {
+        // make sure dates are always created with the same timezone
+        date_default_timezone_set('UTC');
+
+        $allRows = $this->getAllRowsForFile('sheet_with_all_cell_types.xlsx');
+
+        $expectedRows = [
+            [
+                's1--A1', 's1--A2',
+                false, true,
+                \DateTime::createFromFormat('Y-m-d H:i:s', '2015-06-03 13:21:58'),
+                \DateTime::createFromFormat('Y-m-d H:i:s', '2015-06-01 00:00:00'),
+                10, 10.43,
+                null,
+                'weird string', // valid 'str' string
+                null, // invalid date
+            ],
+            ['', '', '', '', '', '', '', '', ''],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
     /**
      * @return void
      */
@@ -222,18 +221,40 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expectedRow, $allRows[0], 'Pronunciation data should be removed.');
     }
 
+
     /**
+     * @return array
+     */
+    public function dataProviderForTestReadShouldBeProtectedAgainstAttacks()
+    {
+        return [
+            ['attack_billion_laughs.xlsx'],
+            ['attack_quadratic_blowup.xlsx'],
+        ];
+    }
+
+    /**
+     * @dataProvider dataProviderForTestReadShouldBeProtectedAgainstAttacks
+     * @NOTE: The LIBXML_NOENT is used to ACTUALLY substitute entities (and should therefore not be used)
+     *
+     * @param string $fileName
      * @return void
      */
-    public function testReadShouldBeProtectedAgainstBillionLaughsAttack()
+    public function testReadShouldBeProtectedAgainstAttacks($fileName)
     {
-        $allRows = $this->getAllRowsForFile('billion_laughs_test_file.xlsx');
+        $startTime = microtime(true);
 
-        $expectedMaxMemoryUsage = 20 * 1024 * 1024; // 20MB
-        $this->assertLessThan($expectedMaxMemoryUsage, memory_get_peak_usage(true), 'Entities should not be expanded and therefore consume all the memory.');
+        try {
+            // using @ to prevent warnings/errors from being displayed
+            @$this->getAllRowsForFile($fileName);
+            $this->fail('An exception should have been thrown');
+        } catch (IOException $exception) {
+            $duration = microtime(true) - $startTime;
+            $this->assertLessThan(10, $duration, 'Entities should not be expanded and therefore take more than 10 seconds to be parsed.');
 
-        $expectedFirstRow = ['s1--A1', 's1--B1', 's1--C1', 's1--D1', 's1--E1'];
-        $this->assertEquals($expectedFirstRow, $allRows[0], 'Entities should be ignored when reading XML files.');
+            $expectedMaxMemoryUsage = 30 * 1024 * 1024; // 30MB
+            $this->assertLessThan($expectedMaxMemoryUsage, memory_get_peak_usage(true), 'Entities should not be expanded and therefore consume all the memory.');
+        }
     }
 
     /**
@@ -260,6 +281,60 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expectedRows, $allRows);
     }
 
+    /**
+     * @return void
+     */
+    public function testReadMultipleTimesShouldRewindReader()
+    {
+        $allRows = [];
+        $resourcePath = $this->getResourcePath('two_sheets_with_inline_strings.xlsx');
+
+        $reader = ReaderFactory::create(Type::XLSX);
+        $reader->open($resourcePath);
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            // do nothing
+        }
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            // this loop should only add the first row of the first sheet
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+                break;
+            }
+
+            // this loop should rewind the iterator and restart reading from the 1st row again
+            // therefore, it should only add the first row of the first sheet
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+                break;
+            }
+
+            // not reading any more sheets
+            break;
+        }
+
+        foreach ($reader->getSheetIterator() as $sheet) {
+            // this loop should only add the first row of the current sheet
+            foreach ($sheet->getRowIterator() as $row) {
+                $allRows[] = $row;
+                break;
+            }
+
+            // not breaking, so we keep reading the next sheets
+        }
+
+        $reader->close();
+
+        $expectedRows = [
+            ['s1 - A1', 's1 - B1', 's1 - C1', 's1 - D1', 's1 - E1'],
+            ['s1 - A1', 's1 - B1', 's1 - C1', 's1 - D1', 's1 - E1'],
+            ['s1 - A1', 's1 - B1', 's1 - C1', 's1 - D1', 's1 - E1'],
+            ['s2 - A1', 's2 - B1', 's2 - C1', 's2 - D1', 's2 - E1'],
+        ];
+        $this->assertEquals($expectedRows, $allRows);
+    }
+
     /**
      * @param string $fileName
      * @return array All the read rows the given file
@@ -272,11 +347,9 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         $reader = ReaderFactory::create(Type::XLSX);
         $reader->open($resourcePath);
 
-        while ($reader->hasNextSheet()) {
-            $reader->nextSheet();
-
-            while ($reader->hasNextRow()) {
-                $allRows[] = $reader->nextRow();
+        foreach ($reader->getSheetIterator() as $sheetIndex => $sheet) {
+            foreach ($sheet->getRowIterator() as $rowIndex => $row) {
+                $allRows[] = $row;
             }
         }
 

tests/Spout/Reader/XLSX/SheetTest.php

@@ -1,14 +1,15 @@
 <?php
 
-namespace Box\Spout\Reader;
+namespace Box\Spout\Reader\XLSX;
 
 use Box\Spout\Common\Type;
+use Box\Spout\Reader\ReaderFactory;
 use Box\Spout\TestUsingResource;
 
 /**
  * Class SheetTest
  *
- * @package Box\Spout\Reader
+ * @package Box\Spout\Reader\XLSX
  */
 class SheetTest extends \PHPUnit_Framework_TestCase
 {
@@ -41,8 +42,8 @@ class SheetTest extends \PHPUnit_Framework_TestCase
         $reader->open($resourcePath);
 
         $sheets = [];
-        while ($reader->hasNextSheet()) {
-            $sheets[] = $reader->nextSheet();
+        foreach ($reader->getSheetIterator() as $sheet) {
+            $sheets[] = $sheet;
         }
 
         $reader->close();

tests/Spout/ReflectionHelper.php

@@ -89,4 +89,27 @@ class ReflectionHelper
 
         return $value;
     }
+
+    /**
+     * Invoke a the given public or protected method on the given object.
+     *
+     * @param object $object
+     * @param string $methodName
+     * @param *mixed|null $params
+     *
+     * @return mixed|null
+     */
+    public static function callMethodOnObject($object, $methodName)
+    {
+        $params = func_get_args();
+        array_shift($params); // object
+        array_shift($params); // methodName
+
+        $className = get_class($object);
+        $class = new ReflectionClass($className);
+        $method = $class->getMethod($methodName);
+        $method->setAccessible(true);
+
+        return $method->invokeArgs($object, $params);
+    }
 }

tests/Spout/Writer/CSV/WriterTest.php

@@ -1,16 +1,18 @@
 <?php
 
-namespace Box\Spout\Writer;
+namespace Box\Spout\Writer\CSV;
 
-use Box\Spout\Common\Type;
 use Box\Spout\TestUsingResource;
+use Box\Spout\Common\Type;
+use Box\Spout\Common\Helper\EncodingHelper;
+use Box\Spout\Writer\WriterFactory;
 
 /**
- * Class CSVTest
+ * Class WriterTest
  *
- * @package Box\Spout\Writer
+ * @package Box\Spout\Writer\CSV
  */
-class CSVTest extends \PHPUnit_Framework_TestCase
+class WriterTest extends \PHPUnit_Framework_TestCase
 {
     use TestUsingResource;
 
@@ -69,7 +71,7 @@ class CSVTest extends \PHPUnit_Framework_TestCase
         ];
         $writtenContent = $this->writeToCsvFileAndReturnWrittenContent($allRows, 'csv_with_utf8_bom.csv');
 
-        $this->assertContains(CSV::UTF8_BOM, $writtenContent, 'The CSV file should contain a UTF-8 BOM');
+        $this->assertContains(EncodingHelper::BOM_UTF8, $writtenContent, 'The CSV file should contain a UTF-8 BOM');
     }
 
     /**
@@ -161,6 +163,6 @@ class CSVTest extends \PHPUnit_Framework_TestCase
     private function trimWrittenContent($writtenContent)
     {
         // remove line feeds and UTF-8 BOM
-        return trim($writtenContent, PHP_EOL . CSV::UTF8_BOM);
+        return trim($writtenContent, PHP_EOL . EncodingHelper::BOM_UTF8);
     }
 }

tests/Spout/Writer/XLSX/Helper/CellHelperTest.php

@@ -1,11 +1,11 @@
 <?php
 
-namespace Box\Spout\Writer\Helper\XLSX;
+namespace Box\Spout\Writer\XLSX\Helper;
 
 /**
  * Class CellHelperTest
  *
- * @package Box\Spout\Writer\Helper\XLSX
+ * @package Box\Spout\Writer\XLSX\Helper
  */
 class CellHelperTest extends \PHPUnit_Framework_TestCase
 {

tests/Spout/Writer/XLSX/SheetTest.php

@@ -1,14 +1,15 @@
 <?php
 
-namespace Box\Spout\Writer;
+namespace Box\Spout\Writer\XLSX;
 
 use Box\Spout\Common\Type;
 use Box\Spout\TestUsingResource;
+use Box\Spout\Writer\WriterFactory;
 
 /**
  * Class SheetTest
  *
- * @package Box\Spout\Writer
+ * @package Box\Spout\Writer\XLSX
  */
 class SheetTest extends \PHPUnit_Framework_TestCase
 {
@@ -69,7 +70,7 @@ class SheetTest extends \PHPUnit_Framework_TestCase
         $this->createGeneratedFolderIfNeeded($fileName);
         $resourcePath = $this->getGeneratedResourcePath($fileName);
 
-        /** @var \Box\Spout\Writer\XLSX $writer */
+        /** @var \Box\Spout\Writer\XLSX\Writer $writer */
         $writer = WriterFactory::create(Type::XLSX);
         $writer->openToFile($resourcePath);
 
@@ -90,18 +91,9 @@ class SheetTest extends \PHPUnit_Framework_TestCase
      */
     private function assertSheetNameEquals($expectedName, $resourcePath, $message = '')
     {
-        $pathToWorkbookFile = $resourcePath . $this->normalizePath('#xl/workbook.xml');
+        $pathToWorkbookFile = $resourcePath . '#xl/workbook.xml';
         $xmlContents = file_get_contents('zip://' . $pathToWorkbookFile);
 
         $this->assertContains('<sheet name="' . $expectedName . '"', $xmlContents, $message);
     }
-
-    /**
-     * @param string $path
-     * @return string The path with the correct directory separators, as defined for the current platform
-     */
-    private function normalizePath($path)
-    {
-        return str_replace('/', DIRECTORY_SEPARATOR, $path);
-    }
 }

tests/Spout/Writer/XLSX/WriterTest.php

@@ -1,16 +1,17 @@
 <?php
 
-namespace Box\Spout\Writer;
+namespace Box\Spout\Writer\XLSX;
 
 use Box\Spout\Common\Type;
 use Box\Spout\TestUsingResource;
+use Box\Spout\Writer\WriterFactory;
 
 /**
  * Class XLSXTest
  *
  * @package Box\Spout\Writer
  */
-class XLSXTest extends \PHPUnit_Framework_TestCase
+class WriterTest extends \PHPUnit_Framework_TestCase
 {
     use TestUsingResource;
 
@@ -230,7 +231,7 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         $this->createGeneratedFolderIfNeeded($fileName);
         $resourcePath = $this->getGeneratedResourcePath($fileName);
 
-        /** @var \Box\Spout\Writer\XLSX $writer */
+        /** @var \Box\Spout\Writer\XLSX\Writer $writer */
         $writer = WriterFactory::create(Type::XLSX);
         $writer->setShouldUseInlineStrings(true);
 
@@ -278,7 +279,7 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         ];
 
         // set the maxRowsPerSheet limit to 2
-        \ReflectionHelper::setStaticValue('\Box\Spout\Writer\Internal\XLSX\Workbook', 'maxRowsPerWorksheet', 2);
+        \ReflectionHelper::setStaticValue('\Box\Spout\Writer\XLSX\Internal\Workbook', 'maxRowsPerWorksheet', 2);
 
         $writer = $this->writeToXLSXFile($dataRows, $fileName, true, $shouldCreateSheetsAutomatically = true);
         $this->assertEquals(2, count($writer->getSheets()), '2 sheets should have been created.');
@@ -302,7 +303,7 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
         ];
 
         // set the maxRowsPerSheet limit to 2
-        \ReflectionHelper::setStaticValue('\Box\Spout\Writer\Internal\XLSX\Workbook', 'maxRowsPerWorksheet', 2);
+        \ReflectionHelper::setStaticValue('\Box\Spout\Writer\XLSX\Internal\Workbook', 'maxRowsPerWorksheet', 2);
 
         $writer = $this->writeToXLSXFile($dataRows, $fileName, true, $shouldCreateSheetsAutomatically = false);
         $this->assertEquals(1, count($writer->getSheets()), 'Only 1 sheet should have been created.');
@@ -348,14 +349,14 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
      * @param string $fileName
      * @param bool $shouldUseInlineStrings
      * @param bool $shouldCreateSheetsAutomatically
-     * @return XLSX
+     * @return Writer
      */
     private function writeToXLSXFile($allRows, $fileName, $shouldUseInlineStrings = true, $shouldCreateSheetsAutomatically = true)
     {
         $this->createGeneratedFolderIfNeeded($fileName);
         $resourcePath = $this->getGeneratedResourcePath($fileName);
 
-        /** @var \Box\Spout\Writer\XLSX $writer */
+        /** @var \Box\Spout\Writer\XLSX\Writer $writer */
         $writer = WriterFactory::create(Type::XLSX);
         $writer->setShouldUseInlineStrings($shouldUseInlineStrings);
         $writer->setShouldCreateNewSheetsAutomatically($shouldCreateSheetsAutomatically);
@@ -373,14 +374,14 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
      * @param string $fileName
      * @param bool $shouldUseInlineStrings
      * @param bool $shouldCreateSheetsAutomatically
-     * @return XLSX
+     * @return Writer
      */
     private function writeToMultipleSheetsInXLSXFile($allRows, $numSheets, $fileName, $shouldUseInlineStrings = true, $shouldCreateSheetsAutomatically = true)
     {
         $this->createGeneratedFolderIfNeeded($fileName);
         $resourcePath = $this->getGeneratedResourcePath($fileName);
 
-        /** @var \Box\Spout\Writer\XLSX $writer */
+        /** @var \Box\Spout\Writer\XLSX\Writer $writer */
         $writer = WriterFactory::create(Type::XLSX);
         $writer->setShouldUseInlineStrings($shouldUseInlineStrings);
         $writer->setShouldCreateNewSheetsAutomatically($shouldCreateSheetsAutomatically);
@@ -408,7 +409,7 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
     private function assertInlineDataWasWrittenToSheet($fileName, $sheetIndex, $inlineData, $message = '')
     {
         $resourcePath = $this->getGeneratedResourcePath($fileName);
-        $pathToSheetFile = $resourcePath . $this->normalizePath('#xl/worksheets/sheet' . $sheetIndex . '.xml');
+        $pathToSheetFile = $resourcePath . '#xl/worksheets/sheet' . $sheetIndex . '.xml';
         $xmlContents = file_get_contents('zip://' . $pathToSheetFile);
 
         $this->assertContains((string)$inlineData, $xmlContents, $message);
@@ -424,7 +425,7 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
     private function assertInlineDataWasNotWrittenToSheet($fileName, $sheetIndex, $inlineData, $message = '')
     {
         $resourcePath = $this->getGeneratedResourcePath($fileName);
-        $pathToSheetFile = $resourcePath . $this->normalizePath('#xl/worksheets/sheet' . $sheetIndex . '.xml');
+        $pathToSheetFile = $resourcePath . '#xl/worksheets/sheet' . $sheetIndex . '.xml';
         $xmlContents = file_get_contents('zip://' . $pathToSheetFile);
 
         $this->assertNotContains((string)$inlineData, $xmlContents, $message);
@@ -439,18 +440,9 @@ class XLSXTest extends \PHPUnit_Framework_TestCase
     private function assertSharedStringWasWritten($fileName, $sharedString, $message = '')
     {
         $resourcePath = $this->getGeneratedResourcePath($fileName);
-        $pathToSharedStringsFile = $resourcePath . $this->normalizePath('#xl/sharedStrings.xml');
+        $pathToSharedStringsFile = $resourcePath . '#xl/sharedStrings.xml';
         $xmlContents = file_get_contents('zip://' . $pathToSharedStringsFile);
 
         $this->assertContains($sharedString, $xmlContents, $message);
     }
-
-    /**
-     * @param string $path
-     * @return string The path with the correct directory separators, as defined for the current platform
-     */
-    private function normalizePath($path)
-    {
-        return str_replace('/', DIRECTORY_SEPARATOR, $path);
-    }
 }

tests/resources/csv/csv_with_empty_last_line.csv

@@ -0,0 +1,2 @@
+csv--11,csv--12,csv--13
+csv--31,csv--32,csv--33

tests/resources/csv/csv_with_encoding_cp1252.csv

@@ -0,0 +1,3 @@
+csv--11,csv--12,csv--13
+csv--21,csv--22,csv--23
+csv--31,csv--32,csv--33

tests/resources/csv/csv_with_utf8_bom.csv

@@ -1,2 +1,3 @@
 csv--11,csv--12,csv--13
-csv--21,csv--22,csv--23
+csv--21,csv--22,csv--23
+csv--31,csv--32,csv--33