From ef7eef710810c8bd0cf9371582ccd0123ff96d4b Mon Sep 17 00:00:00 2001 From: Ignace Nyamagana Butera Date: Tue, 24 Jan 2017 16:36:00 +0100 Subject: [PATCH] Deprecate Methods and Methods calls - deprecate methods - remove Reader::fetch usage - improve StreamIterator --- CHANGELOG.md | 78 ++++++++++++++++++++++++++++++++- composer.json | 2 +- docs/basic-usage.md | 4 +- src/AbstractCsv.php | 16 ++----- src/Modifier/QueryFilter.php | 4 ++ src/Modifier/RowFilter.php | 24 ++++++++++ src/Modifier/StreamIterator.php | 43 ++++++++++-------- src/Reader.php | 47 ++++++++++---------- test/StreamIteratorTest.php | 18 +------- 9 files changed, 159 insertions(+), 77 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c38a79bf..acdaf573 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All Notable changes to `Csv` will be documented in this file -## Next +## 8.2.0 - 2017-01-25 ### Added @@ -10,7 +10,28 @@ All Notable changes to `Csv` will be documented in this file ### Deprecated -- None +- `League\Csv\AbstractCsv::stripBom` +- `League\Csv\Reader::getOffset` +- `League\Csv\Reader::getLimit` +- `League\Csv\Reader::getSortBy` +- `League\Csv\Reader::getFilter` +- `League\Csv\Reader::setOffset` +- `League\Csv\Reader::setLimit` +- `League\Csv\Reader::addSortBy` +- `League\Csv\Reader::addFilter` +- `League\Csv\Reader::fetch` +- `League\Csv\Reader::each` +- `League\Csv\Reader::fetchPairsWithoutDuplicates` +- `League\Csv\Reader::fetchAssoc` +- `League\Csv\Writer::removeFormatter` +- `League\Csv\Writer::hasFormatter` +- `League\Csv\Writer::clearFormatters` +- `League\Csv\Writer::removeValidator` +- `League\Csv\Writer::hasValidator` +- `League\Csv\Writer::clearValidators` +- `League\Csv\Writer::jsonSerialize` +- `League\Csv\Writer::toHTML` +- `League\Csv\Writer::toXML` ### Fixed @@ -216,6 +237,7 @@ All Notable changes to `Csv` will be documented in this file ## 7.0.0 - 2015-02-19 ### Added + - A new flexible mechanism to format and validate a row before its insertion by adding - `Writer::addFormatter` to add a formatter to the `Writer` object - `Writer::removeFormatter` to remove an already registered formatter @@ -232,9 +254,11 @@ All Notable changes to `Csv` will be documented in this file - `League\Csv\Plugin\SkipNullValuesFormatter` to format `null` value on insertion ### Deprecated + - Nothing ### Fixed + - `jsonSerialize`, `toXML` and `toHTML` output can be modified using `Reader` query options methods. - `AbstractCSV::detectDelimiterList` index keys now represents the occurrence of the found delimiter. - `getNewline` and `setNewline` are accessible on the `Reader` class too. @@ -247,6 +271,7 @@ All Notable changes to `Csv` will be documented in this file - `Reader::fetchColumn` will automatically filter out non existing values from the return array ### Removed + - Setting `ini_set("auto_detect_line_endings", true);` is no longer set in the class constructor. Mac OS X users must explicitly set this ini options in their script. - `Writer` and `Reader` default constructor are removed from public API in favor of the named constructors. - All `Writer` methods and constant related to CSV data validation and formatting before insertion @@ -262,6 +287,7 @@ All Notable changes to `Csv` will be documented in this file ## 6.3.0 - 2015-01-21 ### Added + - `AbstractCSV::setOutputBOM` - `AbstractCSV::getOutputBOM` - `AbstractCSV::getInputBOM` @@ -283,6 +309,7 @@ to manage BOM character with CSV. ## 6.2.0 - 2014-12-12 ### Added + - `Writer::setNewline` , `Writer::getNewline` to control the newline sequence character added at the end of each CSV row. ### Deprecated @@ -300,6 +327,7 @@ to manage BOM character with CSV. ## 6.1.0 - 2014-12-08 ### Added + - `Reader::fetchAssoc` now also accepts an integer as first argument representing a row index. ### Deprecated @@ -325,6 +353,7 @@ to manage BOM character with CSV. - Nothing ### Fixed + - Bug Fixed `detectDelimiterList` ### Removed @@ -334,6 +363,7 @@ to manage BOM character with CSV. ## 6.0.0 - 2014-08-28 ### Added + - Stream Filter API in `League\Csv\AbstractCsv` - named constructors `createFromPath` and `createFromFileObject` in `League\Csv\AbstractCsv` to ease CSV object instantiation - `detectDelimiterList` in `League\Csv\AbstractCsv` to replace and remove the use of `RuntimeException` in `detectDelimiter` @@ -341,12 +371,15 @@ to manage BOM character with CSV. - `newWriter` and `newReader` methods in `League\Csv\AbstractCsv` to replace `Writer::getReader` and `Reader::getWriter` ### Deprecated + - Nothing ### Fixed + - `League\Csv\Reader::each` more strict `$callable` MUST returns `true` ### Remove + - `League\Csv\AbstractCsv::detectDelimiter` - `League\Csv\AbstractCsv::setEncoding` and `League\Csv\AbstractCsv::getEncoding` - `League\Csv\Reader::setSortBy` @@ -363,9 +396,11 @@ to manage BOM character with CSV. - `League\Csv\Reader::fetchColumn` replaces `League\Csv\Reader::fetchCol` for naming consistency ### Deprecated + - `League\Csv\Reader::fetchCol` ### Fixed + - Nothing ### Removed @@ -375,12 +410,15 @@ to manage BOM character with CSV. ## 5.3.1 - 2014-04-09 ### Added + - Nothing ### Deprecated + - Nothing ### Fixed + - `$open_mode` default to `r+` in `League\Csv\AbstractCsv` constructors ### Removed @@ -390,12 +428,15 @@ to manage BOM character with CSV. ## 5.3.0 - 2014-03-24 ### Added + - `League\Csv\Writer::setNullHandlingMode` and `League\Csv\Writer::getNullHandlingMode` to handle `null` value ### Deprecated + - Nothing ### Fixed + - `setting ini_set("auto_detect_line_endings", true);` no longer needed for Mac OS ### Removed @@ -405,13 +446,16 @@ to manage BOM character with CSV. ## 5.2.0 - 2014-03-13 ### Added + - `League\Csv\Reader::addSortBy`, `League\Csv\Reader::removeSortBy`, `League\Csv\Reader::hasSortBy`, `League\Csv\Reader::clearSortBy` to improve sorting - `League\Csv\Reader::clearFilter` to align extract filter capabilities to sorting capabilities ### Deprecated + - `League\Csv\Reader::setSortBy` replaced by a better implementation ### Fixed + - `League\Csv\Reader::setOffset` now default to 0; - `League\Csv\Reader::setLimit` now default to -1; - `detectDelimiter` bug fixes @@ -423,14 +467,17 @@ to manage BOM character with CSV. ## 5.1.0 - 2014-03-11 ### Added + - `League\Csv\Reader::each` to ease CSV import data - `League\Csv\Reader::addFilter`, `League\Csv\Reader::removeFilter`, `League\Csv\Reader::hasFilter` to improve extract filter capabilities - `detectDelimiter` method to `League\Csv\AbstractCsv` to sniff CSV delimiter character. ### Deprecated + - `League\Csv\Reader::setFilter` replaced by a better implementation ### Fixed + - Nothing ### Removed @@ -440,12 +487,15 @@ to manage BOM character with CSV. ## 5.0.0 - 2014-02-28 ### Added + - Change namespace from `Bakame\Csv` to `League\Csv` ### Deprecated + - Nothing ### Fixed + - Nothing ### Removed @@ -455,6 +505,7 @@ to manage BOM character with CSV. ## 4.2.1 - 2014-02-22 ### Fixed + - `$open_mode` validation is done by PHP internals directly ### Removed @@ -464,9 +515,11 @@ to manage BOM character with CSV. ## 4.2.0 - 2014-02-17 ### Added + - `toXML` method to transcode the CSV into a XML in `Bakame\Csv\AbstractCsv` ### Fixed + - `toHTML` method bug in `Bakame\Csv\AbstractCsv` - `output` method accepts an optional `$filename` argument - `Bakame\Csv\Reader::fetchCol` default to `$columnIndex = 0` @@ -475,20 +528,24 @@ to manage BOM character with CSV. ## 4.1.2 - 2014-02-14 ### Added + - Move from `PSR-0` to `PSR-4` to autoload the library ## 4.1.1 - 2014-02-14 ### Fixed + - `Bakame\Csv\Reader` methods fixed - `jsonSerialize` bug fixed ## 4.1.0 - 2014-02-07 ### Added + - `getEncoding` and `setEncoding` methods to `Bakame\Csv\AbstractCsv` ### Fixed + - `Bakame\Csv\Writer::insertOne` takes into account CSV controls - `toHTML` method takes into account encoding @@ -500,13 +557,16 @@ to manage BOM character with CSV. - `Bakame\Csv\Writer` and `Bakame\Csv\Reader` extend `Bakame\Csv\AbstractCsv` ### Deprecated + - Nothing ### Fixed + - `Bakame\Csv\Reader::fetchOne` is no longer deprecated - `Bakame\Csv\Reader::fetchCol` no longer accepts a third parameter `$strict` ### Removed + - `Bakame\Csv\Codec` now the library is composer of 2 main classes - `Bakame\Csv\Reader::getFile` - `Bakame\Csv\Reader::fetchValue` @@ -515,50 +575,60 @@ to manage BOM character with CSV. ## 3.3.0 - 2014-01-28 ### Added + - `Bakame\Csv\Reader` implements `IteratorAggregate` Interface - `Bakame\Csv\Reader::createFromString` to create a CSV object from a raw string - `Bakame\Csv\Reader::query` accept an optional `$callable` parameter ### Deprecated + - `Bakame\Csv\Reader::getFile` in favor of `Bakame\Csv\Reader::getIterator` ### Removed + - `Bakame\Csv\ReaderInterface` useless interface ### Fixed + - `Bakame\Csv\Reader::fetch*` `$callable` parameter is normalized to accept an array - `Bakame\Csv\Reader::fetchCol` accepts a third parameter `$strict` ## 3.2.0 - 2014-01-16 ### Added + - `Bakame\Csv\Reader` implements the following interfaces `JsonSerializable` and `ArrayAccess` - `Bakame\Csv\Reader::toHTML` to output the CSV as a HTML table - `Bakame\Csv\Reader::setFilter`, `Bakame\Csv\Reader::setSortBy`, `Bakame\Csv\Reader::setOffset`, `Bakame\Csv\Reader::setLimit`, `Bakame\Csv\Reader::query` to perform SQL like queries on the CSV content. - `Bakame\Csv\Codec::setFlags`, `Bakame\Csv\Codec::getFlags`, Bakame\Csv\Codec::__construct : add an optional `$flags` parameter to enable the use of `SplFileObject` constants flags ### Deprecated + - `Bakame\Csv\Reader::fetchOne` replaced by `Bakame\Csv\Reader::offsetGet` - `Bakame\Csv\Reader::fetchValue` useless method ## 3.1.0 - 2014-01-13 ### Added + - `Bakame\Csv\Reader::output` output the CSV data directly in the output buffer - `Bakame\Csv\Reader::__toString` can be use to echo the raw CSV ## 3.0.1 - 2014-01-10 ### Fixed + - `Bakame\Csv\Reader::fetchAssoc` when users keys and CSV row data don't have the same length ## 3.0.0 - 2014-01-10 ### Added + - `Bakame\Csv\ReaderInterface` - `Bakame\Csv\Reader` class ### Fixed + - `Bakame\Csv\Codec::loadString`returns a `Bakame\Csv\Reader` object - `Bakame\Csv\Codec::loadFile` returns a `Bakame\Csv\Reader` object - `Bakame\Csv\Codec::save` returns a `Bakame\Csv\Reader` object @@ -566,15 +636,19 @@ to manage BOM character with CSV. ## 2.0.0 - 2014-01-09 ### Added + - `Bakame\Csv\CsvCodec` class renamed `Bakame\Csv\Codec` ### Deprecated + - Nothing ### Fixed + - Nothing ### Removed + - `Bakame\Csv\Codec::create` from public API ## 1.0.0 - 2013-12-03 diff --git a/composer.json b/composer.json index 6a40b796..dc0bb02e 100644 --- a/composer.json +++ b/composer.json @@ -43,7 +43,7 @@ }, "extra": { "branch-alias": { - "dev-master": "8.1-dev" + "dev-master": "8.2-dev" } } } diff --git a/docs/basic-usage.md b/docs/basic-usage.md index 12b4c150..eab9b9a5 100644 --- a/docs/basic-usage.md +++ b/docs/basic-usage.md @@ -7,7 +7,7 @@ title: Basic Usage

Tips: Even though you can use the following methods with the League\Csv\Writer object. It is recommended to do so with the League\Csv\Reader class to avoid losing the file cursor position and getting unexpected results when inserting new data.

-Once your CSV object is [instantiated](/instantiation) and [configured](/properties/), you can start interacting with the data using a number of methods available to you. +Once your CSV object is [instantiated](/instantiation) and [configured](/properties/), you can start interacting with the data using a number of methods available to you. ## Iterating over the CSV rows @@ -17,7 +17,7 @@ The CSV object implements PHP's `IteratorAggregate` interface ~~~php getCsvControl(); - $csv->setDelimiter($controls[0]); - $csv->setEnclosure($controls[1]); - $csv->setEscape($controls[2]); - - return $csv; + return new static(new StreamIterator($stream)); } /** @@ -254,7 +244,7 @@ public function newReader($open_mode = 'r+') } /** - * Returns the inner SplFileObject + * Returns the inner CSV Document Iterator object * * @return StreamIterator|SplFileObject */ diff --git a/src/Modifier/QueryFilter.php b/src/Modifier/QueryFilter.php index 35eeba40..9b21786d 100644 --- a/src/Modifier/QueryFilter.php +++ b/src/Modifier/QueryFilter.php @@ -64,6 +64,10 @@ trait QueryFilter /** * Stripping BOM setter * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @param bool $status * * @return $this diff --git a/src/Modifier/RowFilter.php b/src/Modifier/RowFilter.php index 786410fc..4002ba14 100644 --- a/src/Modifier/RowFilter.php +++ b/src/Modifier/RowFilter.php @@ -54,6 +54,10 @@ public function addFormatter(callable $callable) /** * Remove a formatter from the collection * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @param callable $callable * * @return $this @@ -69,6 +73,10 @@ public function removeFormatter(callable $callable) /** * Detect if the formatter is already registered * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @param callable $callable * * @return bool @@ -81,6 +89,10 @@ public function hasFormatter(callable $callable) /** * Remove all registered formatter * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @return $this */ public function clearFormatters() @@ -115,6 +127,10 @@ abstract protected function validateString($str); /** * Remove a validator from the collection * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @param string $name the validator name * * @return $this @@ -130,6 +146,10 @@ public function removeValidator($name) /** * Detect if a validator is already registered * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @param string $name the validator name * * @return bool @@ -144,6 +164,10 @@ public function hasValidator($name) /** * Remove all registered validators * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @return $this */ public function clearValidators() diff --git a/src/Modifier/StreamIterator.php b/src/Modifier/StreamIterator.php index dab73694..edda2213 100644 --- a/src/Modifier/StreamIterator.php +++ b/src/Modifier/StreamIterator.php @@ -26,13 +26,33 @@ */ class StreamIterator implements Iterator { + /** + * Stream pointer + * + * @var resource + */ protected $stream; + /** + * Current iterator value + * + * @var mixed + */ protected $current_line; + /** + * Current iterator key + * + * @var int + */ protected $current_line_number; - protected $flags = SplFileObject::READ_CSV; + /** + * Flags for the StreamIterator + * + * @var int + */ + protected $flags = 0; /** * the field delimiter (one character only) @@ -77,22 +97,6 @@ public function __construct($stream) $this->stream = $stream; } - /** - * Get the delimiter, enclosure and escape character for CSV - * - * @see http://php.net/manual/en/splfileinfo.iswritable.php - * - * @return array - */ - public function getCsvControl() - { - return [ - $this->delimiter, - $this->enclosure, - $this->escape, - ]; - } - /** * Set CSV control * @@ -124,6 +128,7 @@ private function filterControl($char, $type) if (1 == strlen($char)) { return $char; } + throw new InvalidArgumentException(sprintf('The %s character must be a single character', $type)); } @@ -169,7 +174,7 @@ public function fputcsv(array $fields, $delimiter = null, $enclosure = null, $es /** * Retrieves the current line of the file. * - * @return string|array + * @return mixed */ public function current() { @@ -179,10 +184,12 @@ public function current() if (($this->flags & SplFileObject::READ_CSV) == SplFileObject::READ_CSV) { $this->current_line = $this->getCurrentRecord(); + return $this->current_line; } $this->current_line = $this->getCurrentLine(); + return $this->current_line; } diff --git a/src/Reader.php b/src/Reader.php index 79efc749..2e3e2029 100644 --- a/src/Reader.php +++ b/src/Reader.php @@ -44,12 +44,16 @@ class Reader extends AbstractCsv */ public function fetchAll(callable $callable = null) { - return iterator_to_array($this->fetch($callable), false); + return iterator_to_array($this->applyCallable($this->getQueryIterator(), $callable), false); } /** * Fetch the next row from a result set * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * @param callable|null $callable a callable function to be applied to each Iterator item * * @return Iterator @@ -79,6 +83,10 @@ protected function applyCallable(Iterator $iterator, callable $callable = null) /** * Applies a callback function on the CSV * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * The callback function must return TRUE in order to continue * iterating over the iterator. * @@ -89,7 +97,7 @@ protected function applyCallable(Iterator $iterator, callable $callable = null) public function each(callable $callable) { $index = 0; - $iterator = $this->fetch(); + $iterator = $this->getQueryIterator(); $iterator->rewind(); while ($iterator->valid() && true === call_user_func( $callable, @@ -117,7 +125,7 @@ public function fetchOne($offset = 0) { $this->setOffset($offset); $this->setLimit(1); - $iterator = $this->fetch(); + $iterator = $this->getQueryIterator(); $iterator->rewind(); return (array) $iterator->current(); @@ -148,15 +156,17 @@ public function fetchColumn($column_index = 0, callable $callable = null) }; $this->addFilter($filter_column); - $iterator = $this->fetch($select_column); - $iterator = $this->applyCallable($iterator, $callable); - return $iterator; + return $this->applyCallable(new MapIterator($this->getQueryIterator(), $select_column), $callable); } /** * Retrieve CSV data as pairs * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * Fetches an associative array of all rows as key-value pairs (first * column is the key, second column is the value). * @@ -207,21 +217,7 @@ public function fetchPairs($offset_index = 0, $value_index = 1, callable $callab }; $this->addFilter($filter_pairs); - $iterator = $this->fetch($select_pairs); - $iterator = $this->applyCallable($iterator, $callable); - - return $this->generatePairs($iterator); - } - - /** - * Return the key/pairs as a PHP generator - * - * @param Iterator $iterator - * - * @return Generator - */ - protected function generatePairs(Iterator $iterator) - { + $iterator = $this->applyCallable(new MapIterator($this->getQueryIterator(), $select_pairs), $callable); foreach ($iterator as $row) { yield $row[0] => $row[1]; } @@ -230,6 +226,10 @@ protected function generatePairs(Iterator $iterator) /** * Fetch the next row from a result set * + * DEPRECATION WARNING! This method will be removed in the next major point release + * + * @deprecated deprecated since version 8.2 + * * The rows are presented as associated arrays * The callable function will be applied to each row * @@ -254,10 +254,7 @@ public function fetchAssoc($offset_or_keys = 0, callable $callable = null) return array_combine($keys, $row); }; - $iterator = $this->fetch($combine_array); - $iterator = $this->applyCallable($iterator, $callable); - - return $iterator; + return $this->applyCallable(new MapIterator($this->getQueryIterator(), $combine_array), $callable); } /** diff --git a/test/StreamIteratorTest.php b/test/StreamIteratorTest.php index 2c007101..f59b439f 100644 --- a/test/StreamIteratorTest.php +++ b/test/StreamIteratorTest.php @@ -25,24 +25,13 @@ public function tearDown() $this->csv = null; } - /** - * @dataProvider validStream - */ - public function testCreateFromStreamFromStream($stream) + public function testCreateFromStreamFromStream() { - $csv = Reader::createFromStream($stream); + $csv = Reader::createFromStream(fopen(__DIR__.'/data/foo.csv', 'r')); $this->assertInstanceof(Reader::class, $csv); $this->assertInstanceof(StreamIterator::class, $csv->getIterator()); } - public function validStream() - { - return [ - 'stream' => [fopen(__DIR__.'/data/foo.csv', 'r')], - 'StreamIterator' => [new StreamIterator(fopen(__DIR__.'/data/foo.csv', 'r'))], - ]; - } - /** * @expectedException InvalidArgumentException */ @@ -160,7 +149,6 @@ public function testToString() $this->assertSame($expected, $csv->__toString()); } - public function testIteratorWithLines() { $fp = fopen('php://temp', 'r+'); @@ -174,13 +162,11 @@ public function testIteratorWithLines() } $stream = new StreamIterator($fp); - $stream->setFlags(0); $stream->rewind(); $stream->current(); $this->assertInternalType('string', $stream->fgets()); } - public function testCustomNewline() { $fp = fopen('php://temp', 'r+');