Document XmlWriter

docs/include/steps.md

@@ -1,4 +1,5 @@
-First install the [Steps package](https://github.com/portphp/steps):
+First install the [Steps package](https://github.com/portphp/steps), which
+includes the StepAggregator:
 
 ```bash
 $ composer require portphp/steps:1.0.x-dev portphp/portphp:1.0.x-dev

docs/include/todo.md

@@ -1,2 +1,2 @@
 !!! note "To do"
-    Please be patient while we document this part.
+    Please hang on while we document this part.

docs/include/xml.md

@@ -0,0 +1,5 @@
+Install the [XML adapter](https://github.com/portphp/xml):
+
+```bash
+$ composer require portphp/xml:1.0.x-dev portphp/portphp:1.0.x-dev
+```

docs/index.md

@@ -48,7 +48,8 @@ of the Composer documentation.
 
 ## Components
 
-Port consists of several components to aid you in processing data.
+Port consists of several [components](https://packagist.org/packages/portphp/) 
+to aid you in processing data:
 
 1. [Readers](readers.md) read data of different kinds from different sources.
 1. [Writers](writers.md) write data to a database, Excel or CSV file.

docs/upgrading.md

@@ -14,19 +14,21 @@ General
 Workflow
 --------
 
-* Workflow became an interface.
+* The Workflow class became an interface.
 * The default workflow implementation is the [StepAggregator](workflow.md).
 
-CSV
----
+Readers and writers
+-------------------
 
 * For CSV reading and writing, you now need the port/csv package: 
   `$ composer require port/csv`. See the [docs](https://portphp.readthedocs.io) 
   for more information.
-
-Excel
------
-
 * For Excel reading and writing, you now need the port/excel package: 
   `$ composer require port/excel`. See the [docs](https://portphp.readthedocs.io) 
   for more information.
+
+Converters
+----------
+
+* All item converters (MappingItemConverter, NestedMappingItemConverter, CallbackItemConverter) 
+  were removed.

docs/workflow.md

@@ -11,8 +11,8 @@ the following lines:
    the workflow by adding filters, converters, mappers, etc.
 4. Process the workflow. This will read data from the reader, filters and 
    convert the data, and write the output to each of the writers. At the end of
-   the process, a `Result` object is returned which contains counts and 
-   information about (failed) reads and writes.
+   the process, a [Result](#the-workflow-result) object is returned which 
+   contains counts and information about (failed) reads and writes.
 
 In other words, the workflow acts as a *mediator* between a reader and one or 
 more writers, filters and converters. Schematically:
@@ -200,7 +200,7 @@ This is easy. Create a class that implements the `\Port\Steps\Step` interface:
 ```php
 use Port\Steps\Step;
 
-class AwesomeAdditionStep implements Step
+class SpecialAdditionStep implements Step
 {
     public function process(&$item)
     {
@@ -215,7 +215,7 @@ To create a filtering step, to reject the data:
 ```php
 use Port\Steps\Step;
 
-class AwesomeFilteringStep implements Step
+class SpecialFilteringStep implements Step
 {
     public function process(&$item)
     {
@@ -235,6 +235,4 @@ class AwesomeFilteringStep implements Step
 If you even more flexibility, you can implement your own 
 [Workflow](https://github.com/portphp/portphp/blob/master/src/Workflow.php).
 
-!!! note
-    Document more fully.
-
+{!include/todo.md!}

docs/writers.md

@@ -28,7 +28,7 @@ $writer
     ->finish();
 ```
 
-## Doctrine ORM/ODM
+## DoctrineWriter
 
 Writes data through the [Doctrine ORM](http://www.doctrine-project.org/projects/orm.html)
 and [ODM](http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/).
@@ -74,20 +74,6 @@ the import file named 'Category' with an id, the writer will use metadata to get
 reference so that it can be associated properly. The DoctrineWriter will skip any association fields that are already
 objects in cases where a converter was used to retrieve the association.
 
-## PdoWriter
-
-Use the PDO writer for importing data into a relational database (such as
-MySQL, SQLite or MS SQL) without using Doctrine.
-
-```php
-use Port\Writer\PdoWriter;
-
-$pdo = new \PDO('sqlite::memory:');
-$pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
-
-$writer = new PdoWriter($pdo, 'my_table');
-```
-
 ## ExcelWriter
 
 Writes data to an Excel file. 
@@ -128,6 +114,21 @@ existing sheet:
 ```php
 $writer = new ExcelWriter($file, 'Old sheet');
 ```
+
+## PdoWriter
+
+Use the PDO writer for importing data into a relational database (such as
+MySQL, SQLite or MS SQL) without using Doctrine.
+
+```php
+use Port\Writer\PdoWriter;
+
+$pdo = new \PDO('sqlite::memory:');
+$pdo->setAttribute(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION);
+
+$writer = new PdoWriter($pdo, 'my_table');
+```
+
 ## Symfony Console
 
 ### TableWriter
@@ -197,24 +198,84 @@ $output = new ConsoleOutput(...);
 $progressWriter = new ProgressWriter($output, $reader, 'normal', 100);
 ```
 
-## CallbackWriter
+## StreamMergeWriter
+
+Suppose you have two stream writers handling fields differently according to 
+one of the fields. You should then use `StreamMergeWriter` to call the 
+appropriate Writer for you.
 
-Instead of implementing your own writer, you can use the quick solution the
-CallbackWriter offers:
+The default field name is `discr` and can be changed with the
+`setDiscriminantField()` method.
 
 ```php
-use Port\Writer\CallbackWriter;
+<?php
 
-$workflow->addWriter(new CallbackWriter(function ($row) use ($storage) {
-    $storage->store($row);
-}));
+use Port\Writer\StreamMergeWriter;
+
+$writer = new StreamMergeWriter();
+
+$writer->addWriter('first writer', new MyStreamWriter());
+$writer->addWriter('second writer', new MyStreamWriter());
 ```
-## AbstractStreamWriter
+
+## XmlWriter
+
+Writes XML files.
+
+{!include/xml.md!}
+
+First construct PHP’s built-in XMLWriter, then wrap it in `Port\Xml\XmlWriter',
+additionally passing the filename to write to:
+
+```php
+<?php
+
+use Port\Xml\XmlWriter;
+
+$phpXmlWriter = new \XMLWriter();
+$writer = new XmlWriter($phpXmlWriter, 'output-file.xml');
+```
+
+Simply pass the writer to a [workflow](workflow.md) or use the writer on its own:
+
+```php
+<?php
+
+$writer->prepare();
+
+foreach ($data as $item) {
+    $writer->writeItem($item);
+}
+
+$writer->finish();
+```
+
+Pass the root and item elements as the third and fourth arguments:
+
+```php
+<?php
+
+$writer = new XmlWriter(
+    $phpXmlWriter,
+    'output-file.xml',
+    'things', // root item
+    'thing'   // element item
+);
+```
+
+
+## Create a writer
+
+Build your own writer by implementing the Writer interface.
+
+### AbstractStreamWriter
 
 Instead of implementing your own writer from scratch, you can use
 AbstractStreamWriter as a basis. Just implement `writeItem()`:
 
 ```php
+<?php
+
 use Port\Writer\AbstractStreamWriter;
 
 class MyStreamWriter extends AbstractStreamWriter
@@ -237,24 +298,16 @@ rewind($stream);
 echo stream_get_contents($stream);
 ```
 
-## StreamMergeWriter
+### CallbackWriter
 
-Suppose you have 2 stream writers handling fields differently according to one
-of the fields. You should then use `StreamMergeWriter` to call the appropriate
-Writer for you.
-
-The default field name is `discr` and can be changed with the
-`setDiscriminantField()` method.
+You can also use the quick solution the CallbackWriter offers:
 
 ```php
-use Port\Writer\StreamMergeWriter;
+<?php
 
-$writer = new StreamMergeWriter();
+use Port\Writer\CallbackWriter;
 
-$writer->addWriter('first writer', new MyStreamWriter());
-$writer->addWriter('second writer', new MyStreamWriter());
+$workflow->addWriter(new CallbackWriter(function ($row) use ($storage) {
+    $storage->store($row);
+}));
 ```
-
-## Create a writer
-
-Build your own writer by implementing the Writer interface.

mkdocs.yml

@@ -4,11 +4,11 @@ pages:
 - Introduction:
   - index.md
   - quickstart.md
-- COMPONENTS:
+- Components:
   - readers.md
   - writers.md
   - workflow.md
-- ABOUT:
+- About:
   - upgrading.md
   - contributing.md
 site_url: http://portphp.org