Merge pull request thephpleague#379 from thephpleague/feature/tabular-data-reader-interface

Introducing the TabularDataReader interface

Author: nyamsprod

CHANGELOG.md

@@ -7,14 +7,19 @@ All Notable changes to `Csv` will be documented in this file
 ### Added
 
 - More return types and type parameters as supported in PHP7.2+
+- `League\Csv\Statement::create` named constructor to ease constraint builder instantiation
+- `League\Csv\Statement` can now also process `League\Csv\ResultSet` instances.
+- `League\Csv\TabularDataReader` interface to represent how to read tabular data
+- `League\Csv\ResultSet::getRecords` has an optional `$header` second argument to make the method works like `League\Csv\Reader::getRecords` 
+- `League\Csv\ResultSet::createFromReader` create a new instance from `League\Csv\Reader` 
 
 ### Deprecated
 
 - Nothing
 
 ### Fixed
 
-- Nothing
+- `League\Csv\Reader` no longer uses `__call` to implement `fetchOne`, `fetchPairs` and `fetchColumn` methods.
 
 ### Removed
 

phpstan.tests.neon

@@ -9,8 +9,5 @@ parameters:
           path: tests/DetectDelimiterTest.php
         - message: '#Parameter \#1 \$document of static method League\\Csv\\Polyfill\\EmptyEscapeParser::parse\(\) expects League\\Csv\\Stream\|SplFileObject, stdClass given.#'
           path: tests/Polyfill/EmptyEscapeParserTest.php
-        - message: '#Parameter \#1 \$records of method League\\Csv\\Statement::process\(\) expects League\\Csv\\Reader\|League\\Csv\\ResultSet, stdClass given.#'
-          path: tests/ResultSetTest.php
-
     reportUnmatchedIgnoredErrors: true
     checkMissingIterableValueType: false

src/Reader.php

@@ -13,12 +13,8 @@
 
 namespace League\Csv;
 
-use BadMethodCallException;
 use CallbackFilterIterator;
-use Countable;
-use Generator;
 use Iterator;
-use IteratorAggregate;
 use JsonSerializable;
 use League\Csv\Polyfill\EmptyEscapeParser;
 use SplFileObject;
@@ -41,12 +37,8 @@
 
 /**
  * A class to parse and read records from a CSV document.
- *
- * @method array fetchOne(int $nth_record = 0) Returns a single record from the CSV
- * @method Generator fetchColumn(string|int $column_index) Returns the next value from a single CSV record field
- * @method Generator fetchPairs(string|int $offset_index = 0, string|int $value_index = 1) Fetches the next key-value pairs from the CSV document
  */
-class Reader extends AbstractCsv implements Countable, IteratorAggregate, JsonSerializable
+class Reader extends AbstractCsv implements TabularDataReader, JsonSerializable
 {
     /**
      * header offset.
@@ -109,11 +101,7 @@ public function getHeaderOffset(): ?int
     }
 
     /**
-     * Returns the CSV record used as header.
-     *
-     * The returned header is represented as an array of string values
-     *
-     * @return string[]
+     * {@inheritDoc}
      */
     public function getHeader(): array
     {
@@ -153,7 +141,6 @@ protected function setHeader(int $offset): array
 
     /**
      * Returns the row at a given offset.
-     *
      */
     protected function seekRow(int $offset): array
     {
@@ -210,14 +197,25 @@ protected function removeBOM(array $record, int $bom_length, string $enclosure):
     /**
      * {@inheritdoc}
      */
-    public function __call(string $method, array $arguments)
+    public function fetchColumn($index = 0): Iterator
     {
-        static $whitelisted = ['fetchColumn' => 1, 'fetchOne' => 1, 'fetchPairs' => 1];
-        if (isset($whitelisted[$method])) {
-            return (new ResultSet($this->getRecords(), $this->getHeader()))->$method(...$arguments);
-        }
+        return ResultSet::createFromReader($this)->fetchColumn($index);
+    }
 
-        throw new BadMethodCallException(sprintf('%s::%s() method does not exist', static::class, $method));
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchOne(int $nth_record = 0): array
+    {
+        return ResultSet::createFromReader($this)->fetchOne($nth_record);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchPairs($offset_index = 0, $value_index = 1): Iterator
+    {
+        return ResultSet::createFromReader($this)->fetchPairs($offset_index, $value_index);
     }
 
     /**
@@ -249,18 +247,7 @@ public function jsonSerialize(): array
     }
 
     /**
-     * Returns the CSV records as an iterator object.
-     *
-     * Each CSV record is represented as a simple array containing strings or null values.
-     *
-     * If the CSV document has a header record then each record is combined
-     * to the header record and the header record is removed from the iterator.
-     *
-     * If the CSV document is inconsistent. Missing record fields are
-     * filled with null values while extra record fields are strip from
-     * the returned object.
-     *
-     * @param string[] $header an optional header to use instead of the CSV document header
+     * {@inheritDoc}
      */
     public function getRecords(array $header = []): Iterator
     {

src/ResultSet.php

@@ -14,10 +14,7 @@
 namespace League\Csv;
 
 use CallbackFilterIterator;
-use Countable;
-use Generator;
 use Iterator;
-use IteratorAggregate;
 use JsonSerializable;
 use LimitIterator;
 use function array_flip;
@@ -30,7 +27,7 @@
 /**
  * Represents the result set of a {@link Reader} processed by a {@link Statement}.
  */
-class ResultSet implements Countable, IteratorAggregate, JsonSerializable
+class ResultSet implements TabularDataReader, JsonSerializable
 {
     /**
      * The CSV records collection.
@@ -51,8 +48,9 @@ class ResultSet implements Countable, IteratorAggregate, JsonSerializable
      */
     public function __construct(Iterator $records, array $header)
     {
-        $this->records = $records;
         $this->validateHeader($header);
+
+        $this->records = $records;
         $this->header = $header;
     }
 
@@ -74,6 +72,14 @@ public function __destruct()
         unset($this->records);
     }
 
+    /**
+     * Returns a new instance from a League\Csv\Reader object.
+     */
+    public static function createFromReader(Reader $reader): self
+    {
+        return new self($reader->getRecords(), $reader->getHeader());
+    }
+
     /**
      * Returns the header associated with the result set.
      *
@@ -87,15 +93,15 @@ public function getHeader(): array
     /**
      * {@inheritdoc}
      */
-    public function getIterator(): Generator
+    public function getIterator(): Iterator
     {
         return $this->getRecords();
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getRecords(array $header = []): Generator
+    public function getRecords(array $header = []): Iterator
     {
         $this->validateHeader($header);
         $records = $this->combineHeader($header);
@@ -145,13 +151,7 @@ public function jsonSerialize(): array
     }
 
     /**
-     * Returns the nth record from the result set.
-     *
-     * By default if no index is provided the first record of the resultet is returned
-     *
-     * @param int $nth_record the CSV record offset
-     *
-     * @throws Exception if argument is lesser than 0
+     * {@inheritdoc}
      */
     public function fetchOne(int $nth_record = 0): array
     {
@@ -166,13 +166,9 @@ public function fetchOne(int $nth_record = 0): array
     }
 
     /**
-     * Returns a single column from the next record of the result set.
-     *
-     * By default if no value is supplied the first column is fetch
-     *
-     * @param string|int $index CSV column index
+     * {@inheritdoc}
      */
-    public function fetchColumn($index = 0): Generator
+    public function fetchColumn($index = 0): Iterator
     {
         $offset = $this->getColumnIndex($index, __METHOD__.'() expects the column index to be a valid string or integer, `%s` given');
         $filter = static function (array $record) use ($offset): bool {
@@ -246,17 +242,9 @@ protected function getColumnIndexByKey(int $index, string $error_message)
     }
 
     /**
-     * Returns the next key-value pairs from a result set (first
-     * column is the key, second column is the value).
-     *
-     * By default if no column index is provided:
-     * - the first column is used to provide the keys
-     * - the second column is used to provide the value
-     *
-     * @param string|int $offset_index The column index to serve as offset
-     * @param string|int $value_index  The column index to serve as value
+     * {@inheritdoc}
      */
-    public function fetchPairs($offset_index = 0, $value_index = 1): Generator
+    public function fetchPairs($offset_index = 0, $value_index = 1): Iterator
     {
         $offset = $this->getColumnIndex($offset_index, __METHOD__.'() expects the offset index value to be a valid string or integer, `%s` given');
         $value = $this->getColumnIndex($value_index, __METHOD__.'() expects the value index value to be a valid string or integer, `%s` given');

src/Statement.php

@@ -17,7 +17,6 @@
 use CallbackFilterIterator;
 use Iterator;
 use LimitIterator;
-use TypeError;
 use function array_reduce;
 
 /**
@@ -71,21 +70,21 @@ public static function create(callable $where = null, int $offset = 0, int $limi
     /**
      * Set the Iterator filter method.
      */
-    public function where(callable $callable): self
+    public function where(callable $where): self
     {
         $clone = clone $this;
-        $clone->where[] = $callable;
+        $clone->where[] = $where;
 
         return $clone;
     }
 
     /**
      * Set an Iterator sorting callable function.
      */
-    public function orderBy(callable $callable): self
+    public function orderBy(callable $order_by): self
     {
         $clone = clone $this;
-        $clone->order_by[] = $callable;
+        $clone->order_by[] = $order_by;
 
         return $clone;
     }
@@ -135,26 +134,15 @@ public function limit(int $limit): self
     /**
      * Execute the prepared Statement on the {@link Reader} object.
      *
-     * @param Reader|ResultSet $records
-     * @param string[]         $header  an optional header to use instead of the CSV document header
+     * @param string[] $header an optional header to use instead of the CSV document header
      */
-    public function process($records, array $header = []): ResultSet
+    public function process(TabularDataReader $tabular_data, array $header = []): TabularDataReader
     {
-        if (!($records instanceof Reader) && !($records instanceof ResultSet)) {
-            throw new TypeError(sprintf(
-                '%s expects parameter 1 to be a %s or a %s object, %s given',
-                __METHOD__,
-                ResultSet::class,
-                Reader::class,
-                get_class($records)
-            ));
-        }
-
         if ([] === $header) {
-            $header = $records->getHeader();
+            $header = $tabular_data->getHeader();
         }
 
-        $iterator = $records->getRecords($header);
+        $iterator = $tabular_data->getRecords($header);
         $iterator = array_reduce($this->where, [$this, 'filter'], $iterator);
         $iterator = $this->buildOrderBy($iterator);