Improve Code

- Re-introduce JsonSerialize usage for lesser BC break
- Remove Reader Padding Value methods
- Renamed StreamIterator into Document
- Using is_iterable polyfill for PHP7.0
- Improve bundled stream filters
- Improve Error/Exception usage
- Improve Test suite

CHANGELOG.md

@@ -19,11 +19,10 @@ All Notable changes to `Csv` will be documented in this file
     - `League\Csv\CharsetConverter` converts CSV records charset.
     - `League\Csv\XMLConverter` converts CSV records into DOMDocument
     - `League\Csv\HTMLConverter` converts CSV records into HTML table.
-    - `League\Csv\JsonConverter` converts CSV records into a Json string.
 - Improved Exception handling
     - `League\Csv\Exception\CsvException` the default exception interface
     - `League\Csv\Exception\InsertionException`
-    - `League\Csv\Exception\InvalidArgumentException`
+    - `League\Csv\Exception\LengthException`
     - `League\Csv\Exception\LogicException`
     - `League\Csv\Exception\OutOfRangeException`
     - `League\Csv\Exception\RuntimeException`
@@ -56,7 +55,7 @@ All Notable changes to `Csv` will be documented in this file
 - The following method is removed because The BOM API is simplified:
     - `League\Csv\AbstractCsv::stripBOM`
 - All conversion methods are removed in favor of the conversion classes:
-    - `League\Csv\AbstractCsv::jsonSerialize`
+    - `League\Csv\Writer::jsonSerialize`
     - `League\Csv\AbstractCsv::toHTML`
     - `League\Csv\AbstractCsv::toXML`
     - `League\Csv\AbstractCsv::setInputEncoding`

autoload.php

@@ -1,6 +1,6 @@
 <?php
 
-require __DIR__.DIRECTORY_SEPARATOR.'src'.DIRECTORY_SEPARATOR.'functions_include.php';
+require __DIR__.'/src/functions_include.php';
 
 spl_autoload_register(function ($class) {
 
@@ -9,12 +9,7 @@
         return;
     }
 
-    $file = __DIR__
-        .DIRECTORY_SEPARATOR
-        .'src'
-        .DIRECTORY_SEPARATOR
-        .str_replace('\\', DIRECTORY_SEPARATOR, substr($class, strlen($prefix)))
-        .'.php';
+    $file = __DIR__.'/src/'.str_replace('\\', '/', substr($class, strlen($prefix))).'.php';
     if (!is_readable($file)) {
         return;
     }

docs/9.0/connections/bom.md

@@ -37,7 +37,7 @@ The `ByteSequence` interface provides the following constants :
 ~~~php
 <?php
 
-function bom_match(string $str): string
+function League\Csv\bom_match(string $str): string
 ~~~
 
 The `League\Csv\bom_match` function expects a string and returns the BOM sequence found at its start or an empty string otherwise.

docs/9.0/connections/controls.md

@@ -7,6 +7,9 @@ title: Csv character controls
 
 To correctly parse a CSV document you are required to set the character controls to be used by the `Reader` or the `Writer` object.
 
+<p>On error the following the character control setter method will throw a <code>LengthException</code> exception if the submitted string length is not equal to <code>1</code>.</p>
+
+
 ## The delimiter character.
 
 ### Description
@@ -100,8 +103,6 @@ $csv = Reader::createFromFileObject($file);
 echo $csv->getDelimiter(); //display '|'
 ~~~
 
-<p class="message-warning">The escape character is only inherited starting with <code>PHP 7.0.10</code>.</p>
-
 ## Detecting the delimiter character
 
 ~~~php
@@ -110,7 +111,7 @@ echo $csv->getDelimiter(); //display '|'
 function League\Csv\delimiter_detect(Reader $csv, array $delimiters, $limit = 1): array
 ~~~
 
-The `delimiter_detect` function helps detect the possible delimiter character used by the CSV document. This function returns the found occurences of submitted delimiters in a given CSV object.
+The `delimiter_detect` function helps detect the possible delimiter character used by the CSV document. This function returns the number of CSV fields found in the document depending on the submitted delimiters given.
 
 The function takes three (3) arguments:
 
@@ -140,6 +141,8 @@ $result = delimiter_detect($reader, [' ', '|'], 10);
 // - 20 fields were counted with the "|" delimiter in the 10 first records;
 // - in contrast no field was detected for the " " delimiter;
 ~~~
+If the submitted delimiter **is invalid or not found** in the document, `0` will be returned as its associated value.
+
 <p class="message-info">To detect the delimiters stats on the full CSV document you need to set <code>$limit</code> to <code>-1</code>.</p>
-<p class="message-notice"><strong>Notice:</strong> This function only returns hints. Only the CSV providers will validate the real CSV delimiter character.</p>
-<p class="message-warning"><strong>Warning:</strong> This function only test the delimiters you gave it.</p>
+<p class="message-notice">This function only returns hints. Only the CSV providers will validate the real CSV delimiter character.</p>
+<p class="message-warning">This function only test the delimiters you gave it.</p>

docs/9.0/connections/exceptions.md

@@ -29,7 +29,9 @@ try {
 
 ### While setting properties
 
-Setter methods will throw an `InvalidArgumentException` if the submitted value is invalid except for the `createFromPath` which can also triggers a `RuntimeException` if the filename cannot be opened  like [SplFileObject](http://php.net/manual/en/splfileobject.construct.php).
+- A `LengthException` exception is triggered by the CSV character control methods if the submitted character length is not equal to `1`.
+- A `OutOfRangeException` exception is triggered by the library if the submitted integer is not an acceptable value for a given method.
+- A `RuntimeException` exception can also be triggered if the filename cannot be opened like [SplFileObject](http://php.net/manual/en/splfileobject.construct.php).
 
 ~~~php
 <?php
@@ -38,8 +40,8 @@ use League\Csv\Reader;
 
 try {
     $csv = Reader::createFromPath('/path/to/file.csv'); //may trigger a RuntimeException
-    $csv->setDelimiter('toto'); //may trigger a InvalidArgumentException
-} catch (InvalidArgumentException $e) {
+    $csv->setDelimiter('toto'); //may trigger a LengthException
+} catch (LengthException $e) {
     echo $e->getMessage(), PHP_EOL;
 } catch (RuntimeException $e) {
     echo $e->getMessage(), PHP_EOL;
@@ -50,7 +52,7 @@ try {
 try {
     $csv = Reader::createFromPath('/path/to/file.csv');
     $csv->setDelimiter('toto');
-} catch (InvalidArgumentException | RuntimeException $e) {
+} catch (LengthException | RuntimeException $e) {
     echo $e->getMessage(), PHP_EOL;
 }
 ~~~

docs/9.0/connections/filters.md

@@ -70,7 +70,7 @@ The `AbstractCsv::addStreamFilter` method adds a stream filter to the connection
 
 <p class="message-warning">Each time your call <code>addStreamFilter</code> with the same argument the corresponding filter is registered again.</p>
 
-The `AbstractCsv::hasStreamFilter`: tells whether a stream filter is already attached to the connection.
+The `AbstractCsv::hasStreamFilter` method tells whether a specific stream filter is already attached to the connection.
 
 ~~~php
 <?php
@@ -98,11 +98,11 @@ foreach ($reader as $row) {
 
 ## Stream filters removal
 
-Stream filters attached to the ressource **with** `addStreamFilter` are:
+Stream filters attached **with** `addStreamFilter` are:
 
 - removed on the CSV object destruction.
 
-Conversely, stream filters added to the resource **without** `addStreamFilter` are:
+Conversely, stream filters added **without** `addStreamFilter` are:
 
 - not detected by the library.
 - not removed on object destruction.
@@ -121,7 +121,6 @@ $reader->addStreamFilter('convert.utf8decode');
 $reader->addStreamFilter('string.toupper');
 $reader->hasStreamFilter('string.rot13'); //returns false
 $reader = null;
-// only the filters attached using addStreamFilter to `$fp` are removed.
 // 'string.rot13' is still attached to `$fp`
 // filters added using `addStreamFilter` are removed
 ~~~

docs/9.0/connections/instantiation.md

@@ -74,9 +74,9 @@ $reader = Reader::createFromStream(fopen('/path/to/the/file.csv', 'r+'));
 $writer = Writer::createFromStream(tmpfile());
 ~~~
 
-<p class="message-warning"> The resource stream <strong>MUST</strong> be seekable otherwise an <code>InvalidArgumentException</code> exception is thrown.</p>
+<p class="message-warning"> The resource stream <strong>MUST</strong> be seekable otherwise an <code>RuntimeException</code> exception is thrown.</p>
 
-## Loading from a SPL file object
+## Loading from a SplFileObject object
 
 ~~~php
 <?php

docs/9.0/connections/output.md

@@ -59,9 +59,9 @@ can even remove more headers.
 
 use League\Csv\Reader;
 
-header('content-type: text/csv; charset=UTF-8');
-header('content-description: File Transfer');
-header('content-disposition: attachment; filename="name-for-your-file.csv"');
+header('Content-Type: text/csv; charset=UTF-8');
+header('Content-Description: File Transfer');
+header('Content-Disposition: attachment; filename="name-for-your-file.csv"');
 
 $reader = Reader::createFromPath('/path/to/my/file.csv');
 $reader->output();
@@ -97,11 +97,11 @@ The `AbstractCsv::chunk` method takes a single `$length` parameter specifying th
 
 use League\Csv\Reader;
 
-header('transfer-encoding: chunked');
-header('content-encoding: none');
-header('content-type: text/csv; charset=UTF-8');
-header('content-description: File Transfer');
-header('content-disposition: attachment; filename="name-for-your-file.csv"');
+header('Transfer-Encoding: chunked');
+header('Content-Encoding: none');
+header('Content-Type: text/csv; charset=UTF-8');
+header('Content-Description: File Transfer');
+header('Content-Disposition: attachment; filename="name-for-your-file.csv"');
 
 $reader = Reader::createFromPath('/path/to/huge/file.csv', 'r');
 foreach ($reader->chunk(1024) as $chunk) {

docs/9.0/converter/index.md

@@ -12,7 +12,6 @@ The package provides classes which convert any collection of CSV records into:
 - another collection encoded using the [CharsetConverter](/9.0/converter/charset/) class;
 - a `DOMDocument` object using the [XMLConverter](/9.0/converter/xml/) class;
 - a HTML table using the [HTMLConverter](/9.0/converter/html/) class;
-- a Json string using the [JsonConverter](/9.0/converter/json/) class;
 
 <p class="message-warning"><strong>Warning:</strong> A <code>League\Csv\Writer</code> object can not be converted.</p>