Improve documentation

Author: nyamsprod

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All Notable changes to `Csv` will be documented in this file
 
-## Next - 2017-10-20
+## 9.1.0 - 2017-10-20
 
 ### Added
 

docs/9.0/connections/index.md

@@ -81,3 +81,21 @@ try {
 }
 ~~~
 
+When using a non-seekable `SplFileObject`, a `RuntimeException` is thrown instead of a `League\Csv\Exception` when using features that requires a seekable CSV document. In the following example a seekable CSV document is required to update the inserted newline.
+
+~~~php
+<?php
+
+use League\Csv\Exception;
+use League\Csv\Writer;
+
+try {
+    $csv = Writer::createFromFileObject(new SplFileObject('php://output', 'w');
+    $csv->setNewline("\r\n");
+    $csv->insertOne(["foo", "bar"]);
+} catch (Exception | RuntimeException $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+
+//in order to change the CSV document newline a seekable CSV document is required
+~~~

docs/9.0/connections/instantiation.md

@@ -7,7 +7,7 @@ title: Loading CSV documents
 
 Because CSV documents come in different forms we use named constructors to offer several ways to load them.
 
-<p class="message-warning">Since version <code>9.1.0</code> non seekable CSV documents can be used but <code>Exception</code> will be thrown if features requiring seekable CSV document are used.</p>
+<p class="message-warning">Since version <code>9.1.0</code> non seekable CSV documents can be used but <strong>exceptions will be thrown if features requiring seekable CSV document are used.</strong></p>
 
 ## Loading from a string
 
@@ -54,7 +54,13 @@ $reader = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');
 $writer = Writer::createFromPath('/path/to/your/csv/file.csv', 'w');
 ~~~
 
-<p class="message-info"> The <code>$open_mode</code> default to <code>r+</code> if none is supplied.</p>
+<div class="message-notice">
+Starting with version <code>9.1.0</code>, <code>$open_mode</code> default to:
+<ul>
+<li><code>r+</code> for the <code>Writer</code> class</li>
+<li><code>r</code> for the <code>Reader</code> class</li>
+</ul>
+</div>
 
 ## Loading from a resource stream
 

docs/9.0/connections/output.md

@@ -23,7 +23,7 @@ public AbstractCsv::getContent(void): string
 public AbstractCsv::__toString(void): string
 ~~~
 
-<p class="message-notice">The <code>getContent</code> method is added in version <code>9.1.0</code> and replaces the <code>__toString</code> method</p>
+<p class="message-notice">The <code>getContent</code> method is added in version <code>9.1.0</code> and replaces the <code>__toString</code> method which is <strong>deprecated</strong>.</p>
 
 Use the `getContent` method to return the CSV full content.
 
@@ -157,7 +157,7 @@ To avoid breaking the flow of your application, you should create a Response obj
 use League\Csv\Reader;
 
 $reader = Reader::createFromPath('/path/to/my/file.csv', 'r');
-return new Response((string) $reader, 200, [
+return new Response($reader->getContent(), 200, [
     'Content-Encoding' => 'none',
     'Content-Type' => 'text/csv; charset=UTF-8',
     'Content-Disposition' => 'attachment; filename="name-for-your-file.csv"',

docs/9.0/interoperability/rfc4180-field.md

@@ -20,15 +20,15 @@ The `RFC4180Field` class enables to work around the following bugs in PHP's nati
 - [bug #43225](https://bugs.php.net/bug.php?id=43225): `fputcsv` incorrectly handles cells ending in `\` followed by `"`
 - [bug #55413](https://bugs.php.net/bug.php?id=55413): `str_getcsv` doesn't remove escape characters
 - [bug #74713](https://bugs.php.net/bug.php?id=74713): CSV cell split after `fputcsv()` + `fgetcsv()` round trip.
-- [bug #38301](https://bugs.php.net/bug.php?id=38301): field enclosure behavior in fputcsv (since version 9.1)
+- [bug #38301](https://bugs.php.net/bug.php?id=38301): field enclosure behavior in `fputcsv` (since version `9.1.0`)
 
 When using this stream filter you can easily create or read a [RFC4180 compliant CSV document](https://tools.ietf.org/html/rfc4180#section-2) using `League\Csv` connections objects.
 
 
 <p class="message-warning">Changing the CSV objects control characters <strong>after registering the stream filter</strong> may result in unexpected returned records.</p>
 
 
-## Usage with CSV objects
+## Usage with League\CSV objects
 
 ~~~php
 <?php
@@ -48,14 +48,14 @@ The `RFC4180Field::addTo` method will register the stream filter if it is not al
 use League\Csv\RFC4180Field;
 use League\Csv\Writer;
 
-$writer = Writer::createFromPath('php://temp');
+$writer = Writer::createFromPath('php://temp', 'r+');
 $writer->setNewline("\r\n"); //RFC4180 Line feed
 RFC4180Field::addTo($writer); //adding the stream filter to fix field formatting
 $writer->insertAll($iterable_data);
 $writer->output('mycsvfile.csv'); //outputting a RFC4180 compliant CSV Document
 ~~~
 
-<p class="message-notice">the <code>$whitespace_replace</code> argument is available since version 9.1</p>
+<p class="message-notice">the <code>$whitespace_replace</code> argument is available since version <code>9.1.0</code></p>
 
 When the `$whitespace_replace` sequence is different from the empty space and does not contain:
 
@@ -66,16 +66,27 @@ its value will be used to:
 
 - To prevent `fputcsv` default behavior of always using enclosure when a whitespace is found in a record field
 
-<p class="message-warning">The <code>$whitespace_replace</code> sequence should be a sequence not present in the inserted records, otherwise your CSV content will be affected by it.</p>
+~~~php
+<?php
+
+use League\Csv\RFC4180Field;
+use League\Csv\Writer;
 
+$writer = Writer::createFromPath('php://temp', 'r+');
+RFC4180Field::addTo($writer, "\0");
+$writer->insertOne(['foo bar', 'bar']);
+echo $writer->getContent(); //display 'foo bar,bar' instead of '"foo bar",bar'
+~~~
+
+<p class="message-warning">The <code>$whitespace_replace</code> sequence should be a sequence not present in the inserted records, otherwise your CSV content will be affected by it.</p>
 
 ~~~php
 <?php
 
 use League\Csv\RFC4180Field;
 use League\Csv\Writer;
 
-$writer = Writer::createFromPath('php://temp');
+$writer = Writer::createFromPath('php://temp', 'r+');
 RFC4180Field::addTo($writer, 'fo'); // incorrect sequence this will alter your CSV
 $writer->insertOne(['foo bar', 'bar']);
 echo $writer->getContent(); //display ' o bar,baz' instead of foo bar,baz

docs/9.0/reader/index.md

@@ -22,11 +22,9 @@ class Reader extends AbstractCsv implements Countable, IteratorAggregate, JsonSe
 
 The `League\Csv\Reader` class extends the general connections [capabilities](/9.0/connections/) to ease selecting and manipulating CSV document records.
 
-<p class="message-warning">
-By default, the mode for a <code>Reader::createFromPath</code> is
-<code>r+</code> which looks for write permissions on the file and throws an <code>Exception</code> if
-the file cannot be opened with the permission set. For sake of clarity, it is
-strongly suggested to set <code>r</code> mode on the file to ensure it can be opened.</p>
+<p class="message-notice">Starting with version <code>9.1.0</code>, <code>createFromPath</code> when used from the <code>Reader</code> object will have its default set to <code>r</code>.</p>
+
+<p class="message-notice">Prior to <code>9.1.0</code>, by default, the mode for a <code>Reader::createFromPath</code> is <code>r+</code> which looks for write permissions on the file and throws an <code>Exception</code> if the file cannot be opened with the permission set. For sake of clarity, it is strongly suggested to set <code>r</code> mode on the file to ensure it can be opened.</p>
 
 ## CSV example
 

docs/9.0/writer/index.md

@@ -109,6 +109,7 @@ echo $writer->getContent(); // displays "one,two\r\n";
 ~~~
 
 <p class="message-info">The default newline sequence is <code>\n</code>;</p>
+<p class="message-warning">If you are using a non seekable CSV document, changing the newline character will trigger an exception.</p>
 
 ## Flushing the buffer
 

docs/custom.css

@@ -52,4 +52,15 @@ h4:hover .header-permalink,
 h5:hover .header-permalink {
     text-decoration: none;
     color:#777;
+}
+
+main article div>code {
+    display: inline-block;
+    padding: 3px 5px;
+    font-family: Consolas,Monaco,'Andale Mono',monospace;
+    font-size: 17px;
+    line-height: 100%;
+    border-radius: 2px;
+    background: #f5f6f7;
+    border: solid #dcdddd 1px;
 }