diff --git a/Documentation/reference/tasks/_template.md b/Documentation/reference/tasks/_template.md
new file mode 100644
index 00000000..ed1d4a57
--- /dev/null
+++ b/Documentation/reference/tasks/_template.md
@@ -0,0 +1,44 @@
+TaskName
+========
+
+_Describe main goal an use cases of the task_
+
+Task reference
+--------------
+
+* **Service**: `ClassName`
+
+Accepted inputs
+---------------
+
+_Description of allowed types_
+
+Possible outputs
+----------------
+
+_Description of possible types_
+
+Options
+-------
+
+| Code | Type | Required | Default | Description |
+| ---- | ---- | :------: | ------- | ----------- |
+| `code` | `type` | **X** _or nothing_ | `default value` _if available_ | _description_ |
+
+Examples
+--------
+
+_YAML samples and explanations_
+
+* Example 1
+ - details
+ - details
+
+```yaml
+# Task configuration level
+code:
+ service: '@service_ref'
+ options:
+ a: 1
+ b: 2
+```
diff --git a/Documentation/reference/tasks/xml_reader_task.md b/Documentation/reference/tasks/xml_reader_task.md
new file mode 100644
index 00000000..4383f491
--- /dev/null
+++ b/Documentation/reference/tasks/xml_reader_task.md
@@ -0,0 +1,39 @@
+XmlReaderTask
+=============
+
+Open and read an XML file.
+Requires `php-xml`.
+
+Task reference
+--------------
+
+* **Service**: `CleverAge\ProcessBundle\Task\File\Xml\XmlReaderTask`
+
+Accepted inputs
+---------------
+
+No input accepted.
+
+Possible outputs
+----------------
+
+A `\DOMDocument` built from the file.
+
+Options
+-------
+
+| Code | Type | Required | Default | Description |
+| ---- | ---- | :------: | ------- | ----------- |
+| `file_path` | `string` | **X** | | Path of the file to read from (relative to symfony root or absolute) |
+| `mode` | `string` | | `rb` | File open mode (see [fopen mode parameter](https://secure.php.net/manual/en/function.fopen.php)) |
+
+Examples
+--------
+
+```yaml
+# Task configuration level
+my_xml_reader:
+ service: '@CleverAge\ProcessBundle\Task\File\Xml\XmlReaderTask'
+ options:
+ file_path: '%kernel.project_dir%/var/data/file.xml'
+```
diff --git a/Documentation/reference/transformers/_template.md b/Documentation/reference/transformers/_template.md
index f11e3099..d5e98a70 100644
--- a/Documentation/reference/transformers/_template.md
+++ b/Documentation/reference/transformers/_template.md
@@ -3,8 +3,8 @@ TransformerName
_Describe main goal an use cases of the transformer_
-Task reference
---------------
+Transformer reference
+---------------------
* **Service**: `ClassName`
* **Transformer code**: `code`
diff --git a/Documentation/reference/transformers/xpath_evaluator.md b/Documentation/reference/transformers/xpath_evaluator.md
new file mode 100644
index 00000000..43fe7a4e
--- /dev/null
+++ b/Documentation/reference/transformers/xpath_evaluator.md
@@ -0,0 +1,116 @@
+XpathEvaluatorTransformer
+=========================
+
+Manipulate a DOMNode to extract some information using xpath.
+Requires `php-xml`.
+
+**Important** : due to the [behavior of `\DOMXpath::query`](https://www.php.net/manual/en/domxpath.query.php), if you want
+to make a query on a sub element of the full `\DOMDocument` you need to start your query with a `.` to specify the current node.
+
+Task reference
+--------------
+
+* **Service**: `CleverAge\ProcessBundle\Transformer\Xml\XpathEvaluatorTransformer`
+* **Transformer code**: `xpath_evaluator`
+
+Accepted inputs
+---------------
+
+`\DOMNode` only.
+
+Possible outputs
+----------------
+
+Depending on the options :
+- `string`
+- `\DOMNode`
+- `null`
+- an `array` of one of the type above
+
+Options
+-------
+
+| Code | Type | Required | Default | Description |
+| ---- | ---- | :------: | ------- | ----------- |
+| `query` | `string` or `array` | **X** | | One or multiple Xpath queries. Using an array, you can either have a simple list of subqueries, or override some root-level query options |
+| `single_result` | `boolean` | | `true` | Force the result to match a single value |
+| `ignore_missing` | `boolean` | | `true` | Only used with `single_result`, avoid errors if the query doesn't match anything |
+| `unwrap_value` | `boolean` | | `true` | Return the textual content of the node, only works if the result is a `\DOMText` (you might need to use the `text()` xpath selector) or a `\DOMAttr` |
+
+Subqueries, in their complex form, have the following options :
+
+| Code | Type | Required | Default | Description |
+| ---- | ---- | :------: | ------- | ----------- |
+| `subquery` | `string` | **X** | | An Xpath query, no additional sublevel is allowed |
+| `single_result` | `boolean` | | _Root-level value for `single_result`_ | Force the result to match a single value |
+| `ignore_missing` | `boolean` | | _Root-level value for `ignore_missing`_ | Only used with `single_result`, avoid errors if the query doesn't match anything |
+| `unwrap_value` | `boolean` | | _Root-level value for `unwrap_value`_ | Return the textual content of the node, only works if the result is a `\DOMText` (you might need to use the `text()` xpath selector) or a `\DOMAttr` |
+
+
+Examples
+--------
+
+All examples assume this XML
+```xml
+
+
+ ok1
+ ok2
+ ok3
+
+
+ ok4
+ ok5
+ ok6
+
+
+```
+
+* Example 1 : get a single value
+
+```yaml
+# Transformer options level
+xpath_evaluator:
+ query: '/a/b/c[0]/text()'
+```
+
+* Example 2 : get a multiple values
+
+```yaml
+# Transformer options level
+xpath_evaluator:
+ query: '/a/b/c/text()'
+ single_result: false
+```
+
+```yaml
+# Transformer options level
+xpath_evaluator:
+ query:
+ - '/a/d/e/text()'
+ - '/a/d/f/text()'
+ - '/a/d/g/text()'
+```
+
+* Example 3 : get a `\DOMNode`
+
+```yaml
+# Transformer options level
+xpath_evaluator:
+ query: '/a/b'
+ unwrap_value: false
+```
+
+* Example 4 : subquery with partially overridden options
+
+```yaml
+# Transformer options level
+xpath_evaluator:
+ query:
+ all_c_values:
+ subquery: '/a/b/c/text()'
+ single_result: false
+ e_value: '/a/d/e/text()'
+ f_value:
+ subquery: '/a/d/f/text()'
+```
diff --git a/Filesystem/XmlFile.php b/Filesystem/XmlFile.php
new file mode 100644
index 00000000..3a14d49d
--- /dev/null
+++ b/Filesystem/XmlFile.php
@@ -0,0 +1,54 @@
+
+ */
+class XmlFile
+{
+ /** @var \SplFileObject */
+ protected $file;
+
+ /**
+ * XmlFile constructor.
+ *
+ * @param string $path
+ * @param string $mode
+ */
+ public function __construct(string $path, string $mode = 'rb')
+ {
+ $this->file = new \SplFileObject($path, $mode);
+ }
+
+ public function read(): \DOMDocument
+ {
+ $dom = new \DOMDocument();
+ $this->file->rewind();
+ $fileSize = $this->file->getSize();
+ $fileContent = $this->file->fread($fileSize);
+
+ $dom->loadXML($fileContent);
+
+ return $dom;
+ }
+
+ public function write(\DOMDocument $dom)
+ {
+ $content = $dom->saveXML();
+ $result = $this->file->fwrite($content);
+
+ if ($result === null) {
+ throw new \RuntimeException("Could not write content to file");
+ }
+ }
+}
diff --git a/README.md b/README.md
index c481d08b..9acdae8b 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,6 @@ Basically, it will greatly ease the configuration of import and exports but can
- Reference
- [Process definition](Documentation/reference/01-process_definition.md)
- [Task definition](Documentation/reference/02-task_definition.md)
- - [Generic transformers definition](Documentation/reference/03-generic_transformers_definition.md)
- Basic and debug
- [ConstantOutputTask](Documentation/reference/tasks/constant_output_task.md)
- [ConstantIterableOutputTask](Documentation/reference/tasks/constant_iterable_output_task.md)
@@ -44,6 +43,8 @@ Basically, it will greatly ease the configuration of import and exports but can
- File/CSV
- [CsvReaderTask](Documentation/reference/tasks/csv_reader_task.md)
- [CsvWriterTask](Documentation/reference/tasks/csv_writer_task.md)
+ - File/XML
+ - [XmlReaderTask](Documentation/reference/tasks/xml_reader_task.md)
- Flow manipulation
- [AggregateIterableTask](Documentation/reference/tasks/aggregate_iterable_task.md)
- [InputAggregatorTask](Documentation/reference/tasks/input_aggregator_task.md)
@@ -52,6 +53,8 @@ Basically, it will greatly ease the configuration of import and exports but can
- [ArrayFilterTransformer](Documentation/reference/transformers/array_filter_transformer.md)
- [MappingTransformer](Documentation/reference/transformers/mapping_transformer.md)
- [RulesTransformer](Documentation/reference/transformers/rules_transformer.md)
+ - [XpathEvaluatorTransformer](Documentation/reference/transformers/xpath_evaluator.md)
+ - [Generic transformers definition](Documentation/reference/03-generic_transformers_definition.md)
- Examples
- [Simple ETL]
- [Roadmap and versions](Documentation/100-roadmap.md)
diff --git a/Task/File/Xml/XmlReaderTask.php b/Task/File/Xml/XmlReaderTask.php
new file mode 100644
index 00000000..a827741b
--- /dev/null
+++ b/Task/File/Xml/XmlReaderTask.php
@@ -0,0 +1,63 @@
+
+ */
+class XmlReaderTask extends AbstractConfigurableTask
+{
+ /** @var LoggerInterface */
+ protected $logger;
+
+ /**
+ * XmlReaderTask constructor.
+ *
+ * @param LoggerInterface $logger
+ */
+ public function __construct(LoggerInterface $logger)
+ {
+ $this->logger = $logger;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected function configureOptions(OptionsResolver $resolver)
+ {
+ $resolver->setRequired('file_path');
+ $resolver->setAllowedTypes('file_path', 'string');
+
+ $resolver->setDefault('mode', 'rb');
+ $resolver->setAllowedTypes('mode', 'string');
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function execute(ProcessState $state)
+ {
+ if ($state->getInput() !== null) {
+ $this->logger->warning('Input has been ignored for XMLReaderTask');
+ }
+
+ $file = new XmlFile($this->getOption($state, 'file_path'), $this->getOption($state, 'mode'));
+ $state->setOutput($file->read());
+ }
+}
diff --git a/Tests/AbstractProcessTest.php b/Tests/AbstractProcessTest.php
index 1f89f28b..9c5b8390 100644
--- a/Tests/AbstractProcessTest.php
+++ b/Tests/AbstractProcessTest.php
@@ -94,7 +94,7 @@ protected function assertDataQueue(array $expected, string $processName, bool $c
*/
protected function getContainer(): ContainerInterface
{
- if(isset(self::$container)) {
+ if (isset(self::$container)) {
return self::$container;
}
@@ -115,6 +115,22 @@ protected function getContainer(): ContainerInterface
* @throws ExceptionInterface
*/
protected function assertTransformation(string $transformerCode, $expected, $value, array $options = [])
+ {
+ $result = $this->transform($transformerCode, $value, $options);
+ self::assertEquals($expected, $result);
+ }
+
+ /**
+ * Transform some value using referenced transformer with given options
+ *
+ * @param string $transformerCode
+ * @param mixed $value
+ * @param array $options
+ *
+ * @return mixed
+ * @throws ExceptionInterface
+ */
+ protected function transform(string $transformerCode, $value, array $options = [])
{
$transformer = $this->transformerRegistry->getTransformer($transformerCode);
@@ -124,6 +140,6 @@ protected function assertTransformation(string $transformerCode, $expected, $val
$options = $resolver->resolve($options);
}
- self::assertEquals($expected, $transformer->transform($value, $options));
+ return $transformer->transform($value, $options);
}
}
diff --git a/Tests/Transformer/XpathEvaluatorTransformerTest.php b/Tests/Transformer/XpathEvaluatorTransformerTest.php
new file mode 100644
index 00000000..2b78d15b
--- /dev/null
+++ b/Tests/Transformer/XpathEvaluatorTransformerTest.php
@@ -0,0 +1,154 @@
+loadXML('ok');
+ $this->assertTransformation('xpath_evaluator', 'ok', $domDocument, [
+ 'query' => '/a/text()',
+ ]);
+ }
+
+ public function testAttributeValueQuery()
+ {
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML('ko');
+ $this->assertTransformation('xpath_evaluator', 'ok', $domDocument, [
+ 'query' => '/node/@data',
+ ]);
+ }
+
+ public function testSubQuery()
+ {
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML('ok');
+
+ $node = $domDocument->getElementsByTagName('b')[0];
+ $this->assertTransformation('xpath_evaluator', 'ok', $node, [
+ 'query' => './c/text()',
+ ]);
+ }
+
+ public function testMultiResults()
+ {
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML('ok1ok2ok3');
+
+ $node = $domDocument->getElementsByTagName('b')[0];
+ $this->assertTransformation('xpath_evaluator', ['ok1', 'ok2', 'ok3'], $node, [
+ 'query' => './c/text()',
+ 'single_result' => false,
+ ]);
+ }
+
+ public function testMultiResultsAsNodeList()
+ {
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML('ok1ok2ok3');
+
+ $node = $domDocument->getElementsByTagName('b')[0];
+ /** @var \DOMNodeList $result */
+ $result = $this->transform('xpath_evaluator', $node, [
+ 'query' => './c/text()',
+ 'single_result' => false,
+ 'unwrap_value' => false,
+ ]);
+
+ self::assertCount(3, $result);
+ self::assertEquals('ok1', $result[0]->textContent);
+ self::assertEquals('ok2', $result[1]->textContent);
+ self::assertEquals('ok3', $result[2]->textContent);
+ }
+
+ public function testMultiQuery()
+ {
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML('ok1ok2ok3');
+
+ $node = $domDocument->getElementsByTagName('b')[0];
+ $this->assertTransformation('xpath_evaluator', ['ok1', 'ok2', 'ok3'], $node, [
+ 'query' => [
+ './c/text()',
+ './d/text()',
+ './e/text()',
+ ],
+ ]);
+ }
+
+ public function testMultiQueryWithKey()
+ {
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML('ok1ok2ok3');
+
+ $node = $domDocument->getElementsByTagName('b')[0];
+ $this->assertTransformation('xpath_evaluator', [
+ 'c' => 'ok1',
+ 'd' => 'ok2',
+ 'e' => 'ok3',
+ ], $node, [
+ 'query' => [
+ 'c' => './c/text()',
+ 'd' => './d/text()',
+ 'e' => './e/text()',
+ ],
+ ]);
+ }
+
+ public function testOverridableSubqueries()
+ {
+ $xml = <<
+
+ ok1
+ ok2
+ ok3
+
+
+ ok4
+ ok5
+ ok6
+
+
+XML;
+ $domDocument = new \DOMDocument();
+ $domDocument->loadXML($xml);
+
+ $node = $domDocument->getElementsByTagName('b')[0];
+ $this->assertTransformation('xpath_evaluator', [
+ 'all_c_values' => ['ok1', 'ok2', 'ok3'],
+ 'e_value' => 'ok4',
+ 'f_value' => 'ok5',
+ ], $node, [
+ 'query' => [
+ 'all_c_values' => [
+ 'subquery' => '/a/b/c/text()',
+ 'single_result' => false,
+ ],
+ 'e_value' => '/a/d/e/text()',
+ 'f_value' => [
+ 'subquery' => '/a/d/f/text()',
+ ],
+ ],
+ ]);
+ }
+}
diff --git a/Transformer/Xml/XpathEvaluatorTransformer.php b/Transformer/Xml/XpathEvaluatorTransformer.php
new file mode 100644
index 00000000..ba0686ea
--- /dev/null
+++ b/Transformer/Xml/XpathEvaluatorTransformer.php
@@ -0,0 +1,176 @@
+setRequired('query');
+ $resolver->setAllowedTypes('query', ['string', 'array']);
+ $resolver->setNormalizer('query', function(Options $options, $value) {
+ // Basic case : a single query
+ if(\is_string($value)) {
+ return $value;
+ }
+
+ // Complex case : a list of subqueries, each can override root level options
+ if(\is_array($value)) {
+ $queryOptions = [];
+ $queryResolver = new OptionsResolver();
+ $this->configureQueryOptions($queryResolver, $options);
+ $queryResolver->setRequired('subquery');
+ $queryResolver->setAllowedTypes('subquery', 'string');
+
+ foreach ($value as $code => $subquery) {
+ if(\is_string($subquery)) {
+ $subquery = ['subquery' => $subquery];
+ }
+
+ $queryOptions[$code] = $queryResolver->resolve($subquery);
+ }
+
+ return $queryOptions;
+ }
+
+ // This should never be reached
+ throw new \InvalidArgumentException('Unhandled query');
+ });
+
+ // Use same options & defaults for root option level and subquery options
+ $this->configureQueryOptions($resolver);
+ }
+
+ /**
+ * Configure options about how to handle xpath query results.
+ * Available at root and subquery level.
+ *
+ * @param OptionsResolver $resolver
+ * @param Options|null $parentOptions
+ */
+ public function configureQueryOptions(OptionsResolver $resolver, Options $parentOptions = null)
+ {
+ $resolver->setDefault('single_result', $parentOptions ? $parentOptions['single_result'] : true);
+ $resolver->setAllowedTypes('single_result', 'bool');
+
+ $resolver->setDefault('ignore_missing', $parentOptions ? $parentOptions['ignore_missing'] : true);
+ $resolver->setAllowedTypes('ignore_missing', 'bool');
+
+ $resolver->setDefault('unwrap_value', $parentOptions ? $parentOptions['unwrap_value'] : true);
+ $resolver->setAllowedTypes('unwrap_value', 'bool');
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function transform($value, array $options = [])
+ {
+ if (!$value instanceof \DOMNode) {
+ throw new \UnexpectedValueException("Input should be a " . \DOMNode::class);
+ }
+
+ $xpath = $this->buildXpath($value);
+
+ $query = $options['query'];
+ if (\is_array($query)) {
+ $result = \array_map(function ($subquery) use ($xpath, $value, $options) {
+ return $this->query($xpath, $subquery['subquery'], $value, $subquery);
+ }, $query);
+ } else {
+ $result = $this->query($xpath, $query, $value, $options);
+ }
+
+ return $result;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function getCode()
+ {
+ return 'xpath_evaluator';
+ }
+
+ /**
+ * @param \DOMNode $node
+ *
+ * @return \DOMXPath
+ */
+ public function buildXpath(\DOMNode $node): \DOMXPath
+ {
+ $doc = $node instanceof \DOMDocument ? $node : $node->ownerDocument;
+
+ return new \DOMXPath($doc);
+ }
+
+ /**
+ * @param \DOMXPath $xpath
+ * @param string $query
+ * @param \DOMNode $node
+ * @param array $options
+ *
+ * @return mixed
+ */
+ public function query(\DOMXPath $xpath, string $query, \DOMNode $node, array $options)
+ {
+ // TODO check if query is relative ?
+ $nodeList = $xpath->query($query, $node);
+ $results = iterator_to_array($nodeList);
+
+ // Convert results to text
+ if ($options['unwrap_value']) {
+ $results = \array_map(function (\DOMNode $item) use ($query, $options) {
+ if ($item instanceof \DOMAttr) {
+ return $item->value;
+ }
+
+ if ($item instanceof \DOMText) {
+ // If you have an error, remember that you may need to use the "text()" xpath selector
+ return $item->textContent;
+ }
+
+ throw new \UnexpectedValueException("Xpath result cannot be unwrapped for query '{$query}'");
+ }, $results);
+ }
+
+ // Unwrap the node list
+ if ($options['single_result']) {
+ if (count($results) > 1) {
+ throw new \UnexpectedValueException("There is too much results for query '{$query}'");
+ }
+
+ if (count($results) === 0 && !$options['ignore_missing']) {
+ throw new \UnexpectedValueException("There is not enough results for query '{$query}'");
+ }
+
+ if(count($results) === 1) {
+ $results = $results[0];
+ } else {
+ $results = null;
+ }
+
+ }
+
+ return $results;
+ }
+
+}
diff --git a/composer.json b/composer.json
index 9cb59464..2d10787f 100644
--- a/composer.json
+++ b/composer.json
@@ -39,6 +39,7 @@
"require": {
"php": ">=7.1",
"ext-json": "*",
+ "ext-dom": "*",
"symfony/framework-bundle": "~3.0|~4.0",
"symfony/expression-language": "~3.0|~4.0",
"symfony/monolog-bundle": "~3.3",