From bfa3aa8e755377cd6cc2242cfd074e48c7c300ba Mon Sep 17 00:00:00 2001 From: Ignace Nyamagana Butera Date: Fri, 20 Oct 2017 10:03:26 +0200 Subject: [PATCH] Improve documentation --- CHANGELOG.md | 2 +- docs/9.0/connections/index.md | 18 +++++++++++++++++ docs/9.0/connections/instantiation.md | 10 ++++++++-- docs/9.0/connections/output.md | 4 ++-- docs/9.0/interoperability/rfc4180-field.md | 23 ++++++++++++++++------ docs/9.0/reader/index.md | 8 +++----- docs/9.0/writer/index.md | 1 + docs/custom.css | 11 +++++++++++ 8 files changed, 61 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f0b8d59..4fa2e840 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/9.0/connections/index.md b/docs/9.0/connections/index.md index 59f44ed6..2e7481ac 100644 --- a/docs/9.0/connections/index.md +++ b/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 +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 +~~~ \ No newline at end of file diff --git a/docs/9.0/connections/instantiation.md b/docs/9.0/connections/instantiation.md index 4ed51b24..8f62addf 100644 --- a/docs/9.0/connections/instantiation.md +++ b/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. -

Since version 9.1.0 non seekable CSV documents can be used but Exception will be thrown if features requiring seekable CSV document are used.

+

Since version 9.1.0 non seekable CSV documents can be used but exceptions will be thrown if features requiring seekable CSV document are used.

## 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'); ~~~ -

The $open_mode default to r+ if none is supplied.

+
+Starting with version 9.1.0, $open_mode default to: + +
## Loading from a resource stream diff --git a/docs/9.0/connections/output.md b/docs/9.0/connections/output.md index 269a2e94..b70d5b56 100644 --- a/docs/9.0/connections/output.md +++ b/docs/9.0/connections/output.md @@ -23,7 +23,7 @@ public AbstractCsv::getContent(void): string public AbstractCsv::__toString(void): string ~~~ -

The getContent method is added in version 9.1.0 and replaces the __toString method

+

The getContent method is added in version 9.1.0 and replaces the __toString method which is deprecated.

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"', diff --git a/docs/9.0/interoperability/rfc4180-field.md b/docs/9.0/interoperability/rfc4180-field.md index 83716432..f0f3882a 100644 --- a/docs/9.0/interoperability/rfc4180-field.md +++ b/docs/9.0/interoperability/rfc4180-field.md @@ -20,7 +20,7 @@ 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. @@ -28,7 +28,7 @@ When using this stream filter you can easily create or read a [RFC4180 compliant

Changing the CSV objects control characters after registering the stream filter may result in unexpected returned records.

-## Usage with CSV objects +## Usage with League\CSV objects ~~~php 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 ~~~ -

the $whitespace_replace argument is available since version 9.1

+

the $whitespace_replace argument is available since version 9.1.0

When the `$whitespace_replace` sequence is different from the empty space and does not contain: @@ -66,8 +66,19 @@ its value will be used to: - To prevent `fputcsv` default behavior of always using enclosure when a whitespace is found in a record field -

The $whitespace_replace sequence should be a sequence not present in the inserted records, otherwise your CSV content will be affected by it.

+~~~php +insertOne(['foo bar', 'bar']); +echo $writer->getContent(); //display 'foo bar,bar' instead of '"foo bar",bar' +~~~ + +

The $whitespace_replace sequence should be a sequence not present in the inserted records, otherwise your CSV content will be affected by it.

~~~php insertOne(['foo bar', 'bar']); echo $writer->getContent(); //display ' o bar,baz' instead of foo bar,baz diff --git a/docs/9.0/reader/index.md b/docs/9.0/reader/index.md index 5b3ea7ac..bc35e4eb 100644 --- a/docs/9.0/reader/index.md +++ b/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. -

-By default, the mode for a Reader::createFromPath is -r+ which looks for write permissions on the file and throws an Exception if -the file cannot be opened with the permission set. For sake of clarity, it is -strongly suggested to set r mode on the file to ensure it can be opened.

+

Starting with version 9.1.0, createFromPath when used from the Reader object will have its default set to r.

+ +

Prior to 9.1.0, by default, the mode for a Reader::createFromPath is r+ which looks for write permissions on the file and throws an Exception if the file cannot be opened with the permission set. For sake of clarity, it is strongly suggested to set r mode on the file to ensure it can be opened.

## CSV example diff --git a/docs/9.0/writer/index.md b/docs/9.0/writer/index.md index be9715eb..91a1d1e1 100644 --- a/docs/9.0/writer/index.md +++ b/docs/9.0/writer/index.md @@ -109,6 +109,7 @@ echo $writer->getContent(); // displays "one,two\r\n"; ~~~

The default newline sequence is \n;

+

If you are using a non seekable CSV document, changing the newline character will trigger an exception.

## Flushing the buffer diff --git a/docs/custom.css b/docs/custom.css index 7b8f2288..6581a5d8 100644 --- a/docs/custom.css +++ b/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; } \ No newline at end of file