1 files changed, 109 insertions, 45 deletions
diff --git a/examples/stream.php b/examples/stream.php
index cc0249a..9dd9d47 100755
--- a/examples/stream.php
+++ b/examples/stream.php
@@ -9,70 +9,134 @@ use League\Csv\Reader;
 use League\Csv\Writer;
 use lib\FilterTranscode;
 
-require '../vendor/autoload.php';  //load all the classes in dev composer install dev mode
+require '../vendor/autoload.php';  //load all the necessary classes when using composer install in dev mode
 
 //you must register your class for it to be usable by the CSV Lib
 stream_filter_register(FilterTranscode::FILTER_NAME."*", "\lib\FilterTranscode");
+?>
+<!doctype html>
+<html lang="fr">
+<head>
+    <meta charset="utf-8">
+    <title>League\Csv Stream Filter API example</title>
+    <link rel="stylesheet" href="example.css">
+</head>
+<body>
+
+<p>Stream Filters can only be used if the <code><strong>isActiveStreamFilter</strong></code> method returns <code><strong>true</strong></code></p>
+<h3>Using the Reader class</h3>
+
+<pre><code>$reader = Reader::createFromPath(__DIR__.'/data/prenoms.csv');
+if ($reader->isActiveStreamFilter()) {
+    $reader->appendStreamFilter(FilterTranscode::FILTER_NAME."iso-8859-1:utf-8");
+    $reader->appendStreamFilter('string.toupper');
+    $reader->appendStreamFilter('string.rot13');
+}
+$reader->setDelimiter(';');
+$reader->setOffset(6);
+$reader->setLimit(3);
+$res = $reader->fetchAssoc(['Prenom', 'Occurences', 'Sexe', 'Annee']);
+</code></pre>
+
+<p>the data is :</p>
+<ol>
+<li>transcoded by the Stream Filter from ISO-8859-1 to UTF-8</li>
+<li>uppercased</li>
+<li>rot13 transformed</li>
+</ol>
+<?php
 
 //BETWEEN fetch* call you CAN update/remove/add stream filter
 $reader = Reader::createFromPath(__DIR__.'/data/prenoms.csv');
-$reader->appendStreamFilter(FilterTranscode::FILTER_NAME."iso-8859-1:utf-8");
-$reader->appendStreamFilter('string.toupper');
-$reader->appendStreamFilter('string.rot13');
+if ($reader->isActiveStreamFilter()) {
+    $reader->appendStreamFilter(FilterTranscode::FILTER_NAME."iso-8859-1:utf-8");
+    $reader->appendStreamFilter('string.toupper');
+    $reader->appendStreamFilter('string.rot13');
+}
 $reader->setDelimiter(';');
 $reader->setOffset(6);
 $reader->setLimit(3);
 $res = $reader->fetchAssoc(['Prenom', 'Occurences', 'Sexe', 'Annee']);
 
-echo '<pre>
-the data is :
- - transcoded by the Stream Filter from ISO-8859-1 to UTF-8
- - uppercased
- - rot13 transform
-';
-
 var_dump($res);
-
-$reader->removeStreamFilter('string.toupper');
+?>
+<p>Let's remove the <code><strong>string.toupper</strong></code> stream filter</p>
+<pre><code>if ($reader->isActiveStreamFilter()) {
+    $reader->removeStreamFilter('string.toupper');
+}
 $reader->setOffset(6);
 $reader->setLimit(3);
 $res = $reader->fetchAssoc(['Prenom', 'Occurences', 'Sexe', 'Annee']);
 
-echo 'the data is :
- - transcoded by the Stream Filter from ISO-8859-1 to UTF-8
- - rot13 transform
-';
-
-var_dump($res);
-
-// because of the limited support for stream filters with the SplFileObject
-// BETWEEN insert call **YOU CAN NOT UPDATE** stream filters
+var_dump($res);</code></pre>
 
-echo 'Using the Writer:' . PHP_EOL;
-echo 'Filters can only be used with <code><strong>createFromPath</strong></code> method'.PHP_EOL;
+<?php
+if ($reader->isActiveStreamFilter()) {
+    $reader->removeStreamFilter('string.toupper');
+}
+$reader->setOffset(6);
+$reader->setLimit(3);
+$res = $reader->fetchAssoc(['Prenom', 'Occurences', 'Sexe', 'Annee']);
 
-$writer = Writer::createFromPath('/tmp/test.csv', 'w');
-$writer->appendStreamFilter('string.toupper');
+var_dump($res);
+?>
+<h3>Using the Writer class</h3>
+
+<p><strong>You can not add/remove/update stream filters between inserts calls</strong>
+<pre><code>$writer = Writer::createFromPath('/tmp/test.csv', 'w');
+if ($writer->isActiveStreamFilter()) {
+    $writer->appendStreamFilter('string.toupper');
+}
 $writer->insertOne('je,suis,toto,le,héros');
-$writer->appendStreamFilter('string.rot13'); //this stream won't be apploed
+</code></pre>
+<?php
+$writer = Writer::createFromPath('/tmp/test.csv', 'w');
+if ($writer->isActiveStreamFilter()) {
+    $writer->appendStreamFilter('string.toupper');
+}
 $writer->insertOne('je,suis,toto,le,héros');
-
-echo '- the 2 first inserted rows are only uppercased'.PHP_EOL.PHP_EOL
-    .'To update the filters you need to
-    create a new Writer object with a different <code><strong>$open_mode</strong></code>'.PHP_EOL;
-
-$writer = Writer::createFromPath('/tmp/test.csv', 'a+');
-$writer->appendStreamFilter('string.toupper');
-$writer->appendStreamFilter(FilterTranscode::FILTER_NAME."iso-8859-1:utf-8");
-$writer->appendStreamFilter('string.rot13');
-$writer->removeStreamFilter(FilterTranscode::FILTER_NAME."iso-8859-1:utf-8");
+?>
+<p>When the first insert call is done... the stream filter status is
+frozen and can no longer be updated !! Any added row will be uppercased only no matter what.</p>
+<?php
+if ($writer->isActiveStreamFilter()) {
+    $writer->appendStreamFilter('string.rot13');
+    $writer->removeStreamFilter('string.toupper');
+}
 $writer->insertOne('je,suis,toto,le,héros');
+?>
+
+<p>To update the filters you need to:</p>
+<ol>
+<li> create a new Writer object <em>don't forget to update the <code>$open_mode</code></em></li>
+<li>apply the new stream filters</li>
+</ol>
+
+<pre><code>$writer = $writer->newWriter('a+');
+if ($writer->isActiveStreamFilter()) {
+    $writer->appendStreamFilter('string.rot13');
+    $writer->prependStreamFilter('string.strip_tags');
+}
+$writer->insertAll([
+    'je,suis,toto,le,héros',
+    'je,&lt;strong&gt;suis&lt;/strong&gt;,toto,le,héros'
+]);
+echo $writer->newReader()->toHTML();
+</code></pre>
 
-echo 'the following rows are :
- - uppercased
- - rot13 transform
-';
-
-$reader = $writer->newReader();
-$reader->setFlags(SplFileObject::READ_AHEAD|SplFileObject::SKIP_EMPTY);
-var_dump($reader->fetchAll());
+<?php
+$writer = $writer->newWriter('a+');
+if ($writer->isActiveStreamFilter()) {
+    $writer->appendStreamFilter('string.rot13');
+    $writer->prependStreamFilter('string.strip_tags');
+}
+$writer->insertAll([
+    'je,suis,toto,le,héros',
+    'je,<strong>suis</strong>,toto,le,héros'
+]);
+
+echo $writer->newReader()->toHTML(), PHP_EOL;
+?>
+
+</body>
+</html>