From 5bc84c05f297492bb0d4209734b8229263cf97e2 Mon Sep 17 00:00:00 2001 From: David de Boer Date: Sat, 28 Jan 2017 17:03:10 +0100 Subject: [PATCH] Document XmlWriter --- docs/include/steps.md | 3 +- docs/include/todo.md | 2 +- docs/include/xml.md | 5 ++ docs/index.md | 3 +- docs/upgrading.md | 16 +++--- docs/workflow.md | 12 ++-- docs/writers.md | 129 +++++++++++++++++++++++++++++------------- mkdocs.yml | 4 +- 8 files changed, 117 insertions(+), 57 deletions(-) create mode 100644 docs/include/xml.md diff --git a/docs/include/steps.md b/docs/include/steps.md index ef642b4..856eb3d 100644 --- a/docs/include/steps.md +++ b/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 diff --git a/docs/include/todo.md b/docs/include/todo.md index 4f40bd5..1757ec0 100644 --- a/docs/include/todo.md +++ b/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. diff --git a/docs/include/xml.md b/docs/include/xml.md new file mode 100644 index 0000000..5e9789e --- /dev/null +++ b/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 +``` diff --git a/docs/index.md b/docs/index.md index fdb5d63..4c71178 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/upgrading.md b/docs/upgrading.md index 176f07e..b4b9bfb 100644 --- a/docs/upgrading.md +++ b/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. diff --git a/docs/workflow.md b/docs/workflow.md index 92379f9..1f9003a 100644 --- a/docs/workflow.md +++ b/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!} diff --git a/docs/writers.md b/docs/writers.md index 2cdd804..3be0e04 100644 --- a/docs/writers.md +++ b/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; +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 +prepare(); + +foreach ($data as $item) { + $writer->writeItem($item); +} + +$writer->finish(); +``` + +Pass the root and item elements as the third and fourth arguments: + +```php +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. diff --git a/mkdocs.yml b/mkdocs.yml index c5dc36d..abb2e53 100644 --- a/mkdocs.yml +++ b/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