Moved readers to iterators

Instead of the hasNext() / next() syntax, readers now implements the PHP iterator pattern. It allows readers to be used with a foreach() loop. All readers now share the same structure (CSV is treated as having exactly one sheet): - one concrete Reader - one SheetIterator, exposed by the Reader - one or more Sheets, returned at every iteration - one RowIterator, exposed by the Sheet Introducing the concept of sheets for CSV may be kind of confusing but it makes Spout way more consistent. Also, this confusion may be resolved by creating a wrapper around the readers if needed. -- This commit does not delete the old files, not change the folder structure for Writers. This will be done in another commit.
2015-07-26 23:53:17 -07:00
1 parent 322c3d0738
commit ae3ee357ff
@@ -0,0 +1,95 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\AbstractReader2;
+use Box\Spout\Common\Exception\IOException;
+
+/**
+ * Class Reader
+ * This class provides support to read data from a CSV file.
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class Reader extends AbstractReader2
+{
+    /** @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 = '"';
+
+    /**
+     * 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;
+    }
+
+    /**
+     * 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->sheetIterator = new SheetIterator($this->filePointer, $this->fieldDelimiter, $this->fieldEnclosure, $this->globalFunctionsHelper);
+    }
+
+    /**
+     * Returns an iterator to iterate over sheets.
+     *
+     * @return SheetIterator To iterate over sheets
+     */
+    public function getSheetIterator()
+    {
+        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);
+        }
+    }
+}
@@ -0,0 +1,163 @@
+<?php
+
+namespace Box\Spout\Reader\CSV;
+
+use Box\Spout\Reader\IteratorInterface;
+
+/**
+ * Class RowIterator
+ * Iterate over CSV rows.
+ *
+ * @package Box\Spout\Reader\CSV
+ */
+class RowIterator implements IteratorInterface
+{
+    const UTF8_BOM = "\xEF\xBB\xBF";
+
+    /** @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 \Box\Spout\Common\Helper\GlobalFunctionsHelper Helper to work with global functions */
+    protected $globalFunctionsHelper;
+
+    /**
+     * @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 \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($filePointer, $fieldDelimiter, $fieldEnclosure, $globalFunctionsHelper)
+    {
+        $this->filePointer = $filePointer;
+        $this->fieldDelimiter = $fieldDelimiter;
+        $this->fieldEnclosure = $fieldEnclosure;
+        $this->globalFunctionsHelper = $globalFunctionsHelper;
+    }
+
+    /**
+     * Rewind the Iterator to the first element
+     * @link http://php.net/manual/en/iterator.rewind.php
+     *
+     * @return void
+     */
+    public function rewind()
+    {
+        $this->rewindAndSkipUtf8Bom();
+
+        $this->numReadRows = 0;
+        $this->rowDataBuffer = null;
+
+        $this->next();
+    }
+
+    /**
+     * This rewinds and 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 rewindAndSkipUtf8Bom()
+    {
+        $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);
+        }
+    }
+
+    /**
+     * 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
+     */
+    public function next()
+    {
+        $lineData = null;
+        $this->hasReachedEndOfFile = feof($this->filePointer);
+
+        if (!$this->hasReachedEndOfFile) {
+            do {
+               $lineData = $this->globalFunctionsHelper->fgetcsv($this->filePointer, 0, $this->fieldDelimiter, $this->fieldEnclosure);
+           } while ($lineData && $this->isEmptyLine($lineData));
+
+            if ($lineData !== null) {
+                $this->rowDataBuffer = $lineData;
+                $this->numReadRows++;
+            }
+        }
+    }
+
+    /**
+     * @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);
+    }
+
+    /**
+     * Return the current element from the buffer
+     * @link http://php.net/manual/en/iterator.current.php
+     *
+     * @return array
+     */
+    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
+    }
+}
@@ -0,0 +1,35 @@
+<?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 \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($filePointer, $fieldDelimiter, $fieldEnclosure, $globalFunctionsHelper)
+    {
+        $this->rowIterator = new RowIterator($filePointer, $fieldDelimiter, $fieldEnclosure, $globalFunctionsHelper);
+    }
+
+    /**
+     * @return RowIterator
+     */
+    public function getRowIterator()
+    {
+        return $this->rowIterator;
+    }
+}
@@ -0,0 +1,96 @@
+<?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 \Box\Spout\Common\Helper\GlobalFunctionsHelper $globalFunctionsHelper
+     */
+    public function __construct($filePointer, $fieldDelimiter, $fieldEnclosure, $globalFunctionsHelper)
+    {
+        $this->sheet = new Sheet($filePointer, $fieldDelimiter, $fieldEnclosure, $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
+    }
+}