Improve v9 documentation

docs/9.0/bom.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: BOM sequence detection and addition
+---
+
+# BOM sequences
+
+~~~php
+<?php
+
+const AbstractCsv::BOM_UTF8 = "\xEF\xBB\xBF";
+const AbstractCsv::BOM_UTF16_BE = "\xFE\xFF";
+const AbstractCsv::BOM_UTF16_LE = "\xFF\xFE";
+const AbstractCsv::BOM_UTF32_BE = "\x00\x00\xFE\xFF";
+const AbstractCsv::BOM_UTF32_LE = "\xFF\xFE\x00\x00";
+
+public AbstractCsv::getInputBOM(void): string
+public AbstractCsv::getOutputBOM(void): string
+public AbstractCsv::setOutputBOM(string $sequence): AbstractCsv
+~~~
+
+To improve interoperability with programs interacting with CSV, you can manage the presence of the <abbr title="Byte Order Mark">BOM</abbr> sequence in your CSV content.
+
+## Connection constants
+
+To ease BOM sequence manipulation, the `AbstractCsv` class provides the following constants :
+
+* `AbstractCsv::BOM_UTF8` : `UTF-8` `BOM`;
+* `AbstractCsv::BOM_UTF16_BE` : `UTF-16` `BOM` with Big-Endian;
+* `AbstractCsv::BOM_UTF16_LE` : `UTF-16` `BOM` with Little-Endian;
+* `AbstractCsv::BOM_UTF32_BE` : `UTF-32` `BOM` with Big-Endian;
+* `AbstractCsv::BOM_UTF32_LE` : `UTF-32` `BOM` with Little-Endian;
+
+## Detect the currently used BOM sequence
+
+~~~php
+<?php
+
+public AbstractCsv::getInputBOM(void): string
+~~~
+
+Detect the current BOM character is done using the `getInputBOM` method. This method returns the currently used BOM character or an empty string if none is found or recognized.
+
+~~~php
+<?php
+
+use League\Csv\Writer;
+
+$csv = Writer::createFromPath('/path/to/file.csv');
+$bom = $csv->getInputBOM();
+~~~
+
+## Set the outputting BOM sequence
+
+~~~php
+<?php
+
+public AbstractCsv::setOutputBOM(string $sequence): AbstractCsv
+public AbstractCsv::getOutputBOM(void): string
+~~~
+
+- `setOutputBOM`: sets the outputting BOM you want your CSV to be associated with.
+- `getOutputBOM`: get the outputting BOM you want your CSV to be associated with.
+
+~~~php
+<?php
+
+use League\Csv\Reader;
+
+$csv = Reader::createFromPath('/path/to/file.csv');
+$csv->setOutputBOM(Reader::BOM_UTF8);
+$bom = $csv->getOutputBOM(); //returns "\xEF\xBB\xBF"
+~~~
+
+<p class="message-info">The default output <code>BOM</code> character is set to an empty string.</p>
+

docs/9.0/controls.md

@@ -0,0 +1,116 @@
+---
+layout: default
+title: Csv character controls
+---
+
+# CSV character controls
+
+~~~php
+<?php
+
+public AbstractCsv::getDelimiter(void): string
+public AbstractCsv::getEnclosure(void): string
+public AbstractCsv::getEscape(void): string
+public AbstractCsv::setDelimiter(string $delimiter): AbstractCsv
+public AbstractCsv::setEnclosure(string $delimiter): AbstractCsv
+public AbstractCsv::setEscape(string $delimiter): AbstractCsv
+~~~
+
+To parse the CSV document you are required to set the CSV character controls to the `Reader` and `Writer` connections.
+
+## The CSV delimiter character.
+
+### Description
+
+~~~php
+<?php
+
+public AbstractCsv::setDelimiter(string $delimiter): AbstractCsv
+public AbstractCsv::getDelimiter(void): string
+~~~
+
+### Example
+
+~~~php
+<?php
+
+use League\Csv\Reader;
+
+$csv = Reader::createFromPath('/path/to/file.csv');
+$csv->setDelimiter(';');
+$delimiter = $csv->getDelimiter(); //returns ";"
+~~~
+
+<p class="message-info">The default delimiter character is <code>,</code>.</p>
+
+## The enclosure character
+
+### Description
+
+~~~php
+<?php
+
+public AbstractCsv::setEnclosure(string $delimiter): AbstractCsv
+public AbstractCsv::getEnclosure(void): string
+~~~
+
+### Example
+
+~~~php
+<?php
+
+use League\Csv\Writer;
+
+$csv = Writer::createFromPath('/path/to/file.csv');
+$csv->setEnclosure('|');
+$enclosure = $csv->getEnclosure(); //returns "|"
+~~~
+
+<p class="message-info">The default enclosure character is <code>"</code>.</p>
+
+## The escape character
+
+<p class="message-warning"><strong>Warning:</strong> The library does not attempt to workaround <a href="https://bugs.php.net/bug.php?id=55413" target="_blank">a reported bug</a>, <strong>Data using the escape character are correctly escaped but the escape character is not removed from the CSV content</strong>.</p>
+
+
+### Description
+
+~~~php
+<?php
+
+public AbstractCsv::setEscape(string $delimiter): AbstractCsv
+public AbstractCsv::getEscape(void): string
+~~~
+
+### Example
+
+~~~php
+<?php
+
+use League\Csv\Reader;
+
+$csv = Reader::createFromPath('/path/to/file.csv');
+$csv->setEscape('\\');
+$escape = $csv->getEscape(); //returns "\"
+~~~
+
+<p class="message-info">The default escape character is <code>\</code>.</p>
+
+## Inherited character controls
+
+When using a `SplFileObject`, the underlying CSV controls from the submitted object are inherited by the return `AbstractCsv` object.
+
+~~~php
+<?php
+
+$file = new SplTempFileObject();
+$file->setFlags(SplFileObject::READ_CSV);
+$file->setCsvControl('|');
+
+$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>
+

docs/9.0/filters.md

@@ -0,0 +1,102 @@
+---
+layout: default
+title: Controlling PHP Stream Filters
+---
+
+# Stream Filters
+
+~~~php
+<?php
+
+public AbstractCsv::hasStreamFilter(string $filtername): bool
+public AbstractCsv::supportsStreamFilter(void): bool
+public AbstractCsv::addStreamFilter(string $filtername): AbstractCsv
+~~~
+
+To ease performing operations on the CSV as it is being read from or written to, you can add PHP stream filters to the `Reader` and `Writer` connections.
+
+## Detecting PHP stream filter support
+
+~~~php
+<?php
+
+public AbstractCsv::supportsStreamFilter(void): bool
+~~~
+
+Tells whether the stream filter API is supported
+
+~~~php
+<?php
+
+use League\Csv\Reader;
+use League\Csv\Writer;
+
+$reader = Reader::createFromPath('/path/to/my/file.csv');
+$reader->supportsStreamFilter(); //return true
+
+$writer = Writer::createFromFileObject(new SplTempFileObject());
+$writer->supportsStreamFilter(); //return false the API can not be use
+~~~
+
+<p class="message-warning"><strong>Warning:</strong> A <code>LogicException</code> exception may be thrown if you try to use the API under certain circumstances without prior validation using <code>supportsStreamFilter</code></p>
+
+## Adding a PHP stream filter
+
+~~~php
+<?php
+
+public AbstractCsv::addStreamFilter(string $filtername): AbstractCsv
+public AbstractCsv::hasStreamFilter(string $filtername): bool
+~~~
+
+The `$filtername` parameter is a string that represents the filter as registered using php `stream_filter_register` function or one of PHP internal stream filter.
+
+The `AbstractCsv::addStreamFilter` method adds a stream filter to the connection.
+
+<p class="message-notice">Because of the way PHP stream filters are added, you will add multiple times the same filter if you call this method with the same argument.</p>
+
+The `AbstractCsv::hasStreamFilter`: tells whether a stream filter is already attached to the connection.
+
+~~~php
+<?php
+
+use League\Csv\Reader;
+use MyLib\Transcode;
+
+stream_filter_register('convert.utf8decode', Transcode::class);
+// 'MyLib\Transcode' is a class that extends PHP's php_user_filter class
+
+$reader = Reader::createFromPath('/path/to/my/chinese.csv');
+if ($reader->supportsStreamFilter()) {
+	$reader->addStreamFilter('convert.utf8decode');
+	$reader->addStreamFilter('string.toupper');
+}
+
+$reader->hasStreamFilter('string.toupper'); //returns true
+$reader->hasStreamFilter('string.tolower'); //returns false
+
+foreach ($reader as $row) {
+	// each row cell now contains strings that have been:
+	// first UTF8 decoded and then uppercased
+}
+~~~
+
+<p class="message-info">To clear any attached stream filter you need to call the <code>__destruct</code> method.</p>
+
+~~~php
+<?php
+
+use League\Csv\Reader;
+
+$fp = fopen('/path/to/my/chines.csv', 'r');
+$reader = Reader::createFromStream($fp);
+if ($reader->supportsStreamFilter()) {
+	$reader->addStreamFilter('convert.utf8decode');
+	$reader->addStreamFilter('string.toupper');
+}
+
+$reader = null;
+//only the filters attached using addStreamFilter to `$fp` are removed.
+~~~
+
+<p class="message-warning">Only the filters added by the package are removed, filters added to the resource prior to being used in the library are not affected.</p>