Documentation Update: adding toXML documentation and a merge example

README.md

@@ -33,23 +33,29 @@ Install the Bakame.csv package with Composer.
 Usage
 -------
 
-* [Downloading the CSV](examples/download.php)
-* [Converting the CSV into a Json String](examples/json.php)
-* [Converting the CSV into a HTML Table](examples/table.php)
-* [Converting the CSV into a XML file](examples/xml.php)
 * [Selecting specific rows in the CSV](examples/extract.php)
 * [Filtering a CSV](examples/filtering.php)
 * [Creating a CSV](examples/writing.php)
+* [Merging 2 CSV documents](examples/merge.php)
 * [Switching between modes from Writer to Reader mode](examples/switchmode.php)
+* [Downloading the CSV](examples/download.php)
+* [Converting the CSV into a Json String](examples/json.php)
+* [Converting the CSV into a XML file](examples/xml.php)
+* [Converting the CSV into a HTML Table](examples/table.php)
 
-> The CSV file use for the examples is taken from [Paris Opendata](http://opendata.paris.fr/opendata/jsp/site/Portal.jsp?document_id=60&portlet_id=121)
+> The CSV data use for the examples are taken from [Paris Opendata](http://opendata.paris.fr/opendata/jsp/site/Portal.jsp?document_id=60&portlet_id=121)
 
 ### Tips
 
-* When creating a file using the library, first insert all the data that need to be inserted before starting manipulating the CSV. If you manipulate your data before you may change the file cursor position and get unexpected results.
+* When creating a file using the library, first insert all the data that need to be inserted before starting manipulating the CSV. If you manipulate your data before insertion, you may change the file cursor position and get unexpected results.
 
 * If you are dealing with non-unicode data, specify the encoding parameter using the `setEncoding` method otherwise your output conversions may no work.
 
+* When merging multiples CSV documents don't forget to set the main CSV object
+ as a `Bakame\Csv\Writer` object with the `$open_mode = 'a+'` to preserve its content.
+ This setting is of course not required when your main `Bakame\Csv\Writer` object is 
+ created from String
+
 * **If you are on a Mac OS X Server**, add the following lines before using the library to help [PHP detect line ending in Mac OS X](http://php.net/manual/en/function.fgetcsv.php#refsect1-function.fgetcsv-returnvalues).
 
 ```php
@@ -135,35 +141,38 @@ echo $writer;
 echo $writer->__toString();
 ```
 
-Use the `toHTML` method to format the CSV data into an HTML table. This method accepts an optional argument `$classname` to help you customize the table rendering, by defaut the classname given to the table is `table-csv-data`.
-
-```php
-echo $writer->toHTML('table table-bordered table-hover');
-```
-
-#### convert the CSV into an XML string:
+#### convert to XML:
 
-Use the `toXML` method to format the CSV data into an XML String. This methods accepts 3 optionals arguments `$root_name`, `$row_name`, `$cell_name` to help you customize the XML tree. 
+Use the `toXML` method to convert the CSV data into a PHP `DomDocument` object. This method accepts 3 optionals arguments `$root_name`, `$row_name`, `$cell_name` to help you customize the XML tree. 
 
 By default:
 * `$root_name = 'csv'` 
 * `$row_name = 'row'` 
 * `$cell_name = 'cell'` 
 
 ```php
-echo $writer->toXML('data', 'item', 'cell');
+$dom = $writer->toXML('data', 'item', 'cell');
+```
+
+#### convert to HTML table:
+
+Use the `toHTML` method to format the CSV data into an HTML table. This method accepts an optional argument `$classname` to help you customize the table rendering, by defaut the classname given to the table is `table-csv-data`.
+
+```php
+echo $writer->toHTML('table table-bordered table-hover');
 ```
 
-#### convert the CSV into a Json string:
+#### convert to Json
 
 Use the `json_encode` function directly on the instantiated object.
 
 ```php
 echo json_encode($writer);
-
 ```
 
-#### make the CSV downloadable
+**Of Note:** When using the `toHTML`, `toXML` methods and the `json_encode` function, the data is internally convert if needed into `UTF-8`.
+
+#### download the CSV
 
 If you only wish to make your CSV downloadable just use the `output` method to return to the output buffer the CSV content.
 

examples/merge.php

@@ -0,0 +1,81 @@
+<?php
+
+use Bakame\Csv\Writer;
+use Bakame\Csv\Reader;
+
+require '../vendor/autoload.php';
+
+//we are creating a CSV from a raw string
+$rawCsv = <<<EOF
+Melodie;6;F;2011
+Melody;7;F;2011
+Melvil;13;M;2011
+Melvin;9;M;2011
+Menahem;6;M;2011
+Mendel;7;M;2011
+Meriem;8;F;2011
+Merlin;8;M;2011
+Meryam;7;F;2011
+EOF;
+
+$writer = Writer::createFromString($rawCsv);
+//because we raw string delimiter is ";"
+//the string delimiter MUST also be ";"
+$writer->setDelimiter(';');
+
+//we are creating a CSV from a raw string
+$rawCsv2Merge = <<<EOF
+Ben,7,M,2007
+Benjamin,78,M,2007
+Benoît,17,M,2007
+Berenice,19,F,2007
+Bertille,9,F,2007
+Bianca,18,F,2007
+Bilal,26,M,2007
+Bilel,7,M,2007
+EOF;
+
+$csv2merge = Reader::createFromString($rawCsv2Merge);
+//because we raw string delimiter is ";"
+//the string delimiter MUST also be ","
+$csv2merge->setDelimiter(',');
+
+/*
+ When merging multiples CSV documents don't forget to set the main CSV object
+ as a `Bakame\Csv\Writer` object with the $open_mode = 'a+' to preserve its content.
+ This setting is of course not required when your main CSV object is created from String
+*/
+
+?>
+<!doctype html>
+<html lang="fr">
+<head>
+    <meta charset="utf-8">
+    <title>Merging 2 CSV documents</title>
+    <link rel="stylesheet" href="example.css">
+</head>
+<body>
+<h1>Using the Bakame\Csv\Writer class to merge two CSV documents</h1>
+<h3>The main Raw CSV</h3>
+<p><em>The delimiter is a ";"</em></p>
+<pre>
+<?=$writer?>
+</pre>
+<h3>The Raw CSV to be merge</h3>
+<p><em>The delimiter is a ";"</em></p>
+<pre>
+<?=$csv2merge?>
+</pre>
+<?php $writer->insertAll($csv2merge); //we are merging both documents as simple as that!!?>
+<h3>The Raw CSV after merging</h3>
+<p><em>Notice that after merging the data is semi-colon ";" separated</em></p>
+<pre>
+<?=$writer?>
+</pre>
+<h3>Tips</h3>
+<p> When merging multiples CSV documents don't forget to set the main CSV object
+ as a <code>Bakame\Csv\Writer</code> object with the <code>$open_mode = 'a+'</code>
+ to preserve its content. This setting is of course not required when your main CSV object
+ is created from String</p>
+</body>
+</html>

examples/xml.php

@@ -10,7 +10,8 @@
 $inputCsv = new Reader('data/prenoms.csv');
 $inputCsv->setEncoding('ISO-8859-15');
 $inputCsv->setDelimiter(';');
-$xml = $inputCsv->toXML('csv', 'ligne', 'cellule');
+$doc = $inputCsv->toXML('csv', 'ligne', 'cellule');
+$xml = $doc->saveXML();
 header('Content-Type: application/xml; charset="utf-8"');
 header('Content-Length: '.strlen($xml));
 die($xml);