chore(doc) #22 Add missing documentations

CHANGELOG.md

@@ -3,6 +3,7 @@ Latest
 
 ### Changes
 * [#20](https://github.com/cleverage/soap-process-bundle/issues/20) Update quality stack: use Rector `withComposerBased()` sets (removed `SYMFONY_64` / `PHPUNIT_100` sets), declare used Symfony packages and PHPUnit range in composer.json, apply quality tools fixes
+* [#22](https://github.com/cleverage/soap-process-bundle/issues/22) Add missing documentations: reference pages for Client, RequestTask & RequestTransformer, cookbooks. Harmonize and fix existing documentation.
 
 v3.0
 ------

README.md

@@ -13,7 +13,7 @@ For usage documentation, see:
 
 ## Support & Contribution
 
-For general support and questions, please use [Github](https://github.com/cleverage/rest-process-bundle/issues).
+For general support and questions, please use [Github](https://github.com/cleverage/soap-process-bundle/issues).
 If you think you found a bug or you have a feature idea to propose, feel free to open an issue after looking at the [contributing](CONTRIBUTING.md) guide.
 
 ## License

docs/cookbooks/soap_call_and_export.md

@@ -0,0 +1,81 @@
+Call a SOAP service and export the response
+===========================================
+
+This recipe calls a SOAP method returning a list, filters and maps the response, then writes it to a CSV file.
+It uses the public [CountryInfoService](http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso)
+through the `country_info` client declared in the [client reference](../reference/client.md#examples).
+
+```yaml
+clever_age_process:
+    configurations:
+        app.soap_export_european_countries:
+            description: 'Export the European countries from the CountryInfoService'
+            tasks:
+                list_countries:
+                    service: '@CleverAge\SoapProcessBundle\Task\RequestTask'
+                    error_strategy: stop
+                    options:
+                        client: country_info
+                        method: FullCountryInfoAllCountries
+                    outputs: [extract]
+
+                extract:
+                    service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+                    options:
+                        transformers:
+                            property_accessor: # Get the list of countries from the stdClass response
+                                property_path: 'FullCountryInfoAllCountriesResult.tCountryInfo'
+                            array_filter:
+                                condition:
+                                    match:
+                                        sContinentCode: 'EU'
+                            array_map:
+                                transformers:
+                                    cast: # Convert each stdClass to an array
+                                        type: array
+                                    mapping:
+                                        mapping:
+                                            iso_code:
+                                                code: '[sISOCode]'
+                                            name:
+                                                code: '[sName]'
+                                            capital:
+                                                code: '[sCapitalCity]'
+                                            phone_code:
+                                                code: '[sPhoneCode]'
+                                            currency:
+                                                code: '[sCurrencyISOCode]'
+                    outputs: [iterate]
+
+                iterate:
+                    service: '@CleverAge\ProcessBundle\Task\InputIteratorTask'
+                    outputs: [write]
+
+                write:
+                    service: '@CleverAge\ProcessBundle\Task\File\Csv\CsvWriterTask'
+                    options:
+                        file_path: '%kernel.project_dir%/var/exports/european_countries_{date}.csv'
+                        headers: [iso_code, name, capital, phone_code, currency]
+```
+
+How it works:
+- The [RequestTask](../reference/tasks/request_task.md) has no input (it is the first task), so the
+  `FullCountryInfoAllCountries` method is called without argument. The response is a `stdClass` built by `SoapClient`.
+  With `error_strategy: stop`, a failed call (logged with the last request and response) stops the process.
+- The [TransformerTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/transformer_task.md)
+  reads the list of countries in the response with
+  [property_accessor](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/property_accessor_transformer.md),
+  keeps the European ones with
+  [array_filter](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/array_filter_transformer.md),
+  then converts each `stdClass` to an array
+  ([cast](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/cast_transformer.md)) and
+  renames its keys ([mapping](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/mapping_transformer.md))
+  inside [array_map](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/array_map_transformer.md).
+- The [InputIteratorTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/input_iterator_task.md)
+  outputs the countries one by one to the
+  [CsvWriterTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/csv_writer_task.md).
+
+Note that the client sets the `SOAP_SINGLE_ELEMENT_ARRAYS` feature: without it, `tCountryInfo` would be a single
+`stdClass` instead of a list if the service returned only one country. Also, a failed call stops the process without
+marking it as failed (see [RequestTask notes](../reference/tasks/request_task.md#notes)): monitor the error logs of
+the `cleverage_process_task` channel.

docs/cookbooks/soap_enrich_csv.md

@@ -0,0 +1,130 @@
+Enrich a CSV file with a SOAP service
+=====================================
+
+This recipe reads a CSV file of country codes, calls a SOAP method for each line, and writes the enriched lines to
+another CSV file. Lines for which the call fails are logged and skipped. It uses the public
+[CountryInfoService](http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso) through the
+`country_info` client declared in the [client reference](../reference/client.md#examples).
+
+Source file `var/data/countries.csv`:
+
+```csv
+iso;label
+FR;Our label for France
+DE;Our label for Germany
+```
+
+```yaml
+clever_age_process:
+    configurations:
+        app.soap_enrich_countries:
+            description: 'Add the capital city and currency of each country'
+            tasks:
+                read:
+                    service: '@CleverAge\ProcessBundle\Task\File\Csv\CsvReaderTask'
+                    options:
+                        file_path: '%kernel.project_dir%/var/data/countries.csv'
+                    outputs: [build_arguments]
+
+                build_arguments:
+                    service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+                    options:
+                        transformers:
+                            mapping: # { parameters: { sCountryISOCode: FR } }
+                                mapping:
+                                    parameters:
+                                        code: '[iso]'
+                                        transformers:
+                                            wrapper:
+                                                wrapper_key: sCountryISOCode
+                    outputs: [get_country]
+
+                get_country:
+                    service: '@CleverAge\SoapProcessBundle\Task\RequestTask'
+                    error_strategy: skip
+                    options:
+                        client: country_info
+                        method: FullCountryInfo
+                    outputs: [map_response]
+                    error_outputs: [log_error]
+
+                log_error:
+                    service: '@CleverAge\ProcessBundle\Task\Reporting\LoggerTask'
+                    options:
+                        level: warning
+                        message: 'FullCountryInfo call failed, line skipped'
+
+                map_response:
+                    service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+                    options:
+                        transformers:
+                            property_accessor:
+                                property_path: FullCountryInfoResult
+                            cast:
+                                type: array
+                            mapping:
+                                mapping:
+                                    iso:
+                                        code: '[sISOCode]'
+                                    name:
+                                        code: '[sName]'
+                                    capital:
+                                        code: '[sCapitalCity]'
+                                    currency:
+                                        code: '[sCurrencyISOCode]'
+                    outputs: [write]
+
+                write:
+                    service: '@CleverAge\ProcessBundle\Task\File\Csv\CsvWriterTask'
+                    options:
+                        file_path: '%kernel.project_dir%/var/exports/countries_enriched_{date}.csv'
+                        headers: [iso, name, capital, currency]
+```
+
+How it works:
+- [CsvReaderTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/csv_reader_task.md) is
+  iterable: each line goes through the following tasks before the next one is read, so one SOAP call is made per line.
+- The first [TransformerTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/transformer_task.md)
+  builds the arguments of the SOAP method with the
+  [mapping](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/mapping_transformer.md)
+  and [wrapper](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/wrapper_transformer.md)
+  transformers: `FullCountryInfo` is a document/literal method expecting a single `parameters` structure.
+- The [RequestTask](../reference/tasks/request_task.md) calls `FullCountryInfo` with these arguments. With
+  `error_strategy: skip`, a failed call is logged by the task, `false` is sent to the
+  [LoggerTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/logger_task.md) of the
+  `error_outputs`, and the line is not written.
+- The second TransformerTask extracts the result from the `stdClass` response
+  ([property_accessor](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/property_accessor_transformer.md)),
+  converts it to an array ([cast](https://github.com/cleverage/process-bundle/blob/main/docs/reference/transformers/cast_transformer.md))
+  and maps the columns to write with the
+  [CsvWriterTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/csv_writer_task.md).
+
+Note that the error output of the RequestTask is `false`, not the CSV line: the details of the failed call (options,
+last request and response) are in the log context of the `Empty resultset for query` error logged by the task.
+
+To add a single value to the line instead of replacing it, the SOAP call can also be done inside a `mapping` with the
+[RequestTransformer](../reference/transformers/request_transformer.md) (`soap_request`), e.g. with `keep_input: true`:
+
+```yaml
+# Task configuration level
+add_country_name:
+  service: '@CleverAge\ProcessBundle\Task\TransformerTask'
+  options:
+    transformers:
+      mapping:
+        keep_input: true
+        mapping:
+          name:
+            code: '[iso]'
+            transformers:
+              wrapper:
+                wrapper_key: sCountryISOCode
+              wrapper#2:
+                wrapper_key: parameters
+              soap_request:
+                client: country_info
+                method: CountryName
+              property_accessor:
+                property_path: CountryNameResult
+  outputs: [write]
+```

docs/index.md

@@ -1,6 +1,7 @@
 ## Prerequisite
 
-CleverAge/ProcessBundle must be [installed](https://github.com/cleverage/process-bundle/blob/main/docs/01-quick_start.md#installation.
+CleverAge/ProcessBundle must be [installed](https://github.com/cleverage/process-bundle/blob/main/docs/01-quick_start.md#installation).
+The PHP [soap](https://www.php.net/manual/en/book.soap.php) extension is required.
 
 ## Installation
 
@@ -19,9 +20,36 @@ Remember to add the following line to config/bundles.php (not required if Symfon
 CleverAge\SoapProcessBundle\CleverAgeSoapProcessBundle::class => ['all' => true],
 ```
 
+## Configuration
+
+The bundle has no configuration. Declare at least one SOAP client as a service tagged `cleverage.soap.client`, its
+`code` is then used by the `client` option of the task and the transformer (see [Client](reference/client.md)):
+
+```yaml
+# config/services.yaml
+services:
+    app.cleverage_soap_process.client.country_info:
+        class: CleverAge\SoapProcessBundle\Client\Client
+        arguments:
+            $logger: '@logger'
+            $code: 'country_info'
+            $wsdl: 'http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL'
+            $options:
+                exceptions: true
+                features: !php/const SOAP_SINGLE_ELEMENT_ARRAYS
+        tags:
+            - { name: cleverage.soap.client }
+```
+
 ## Reference
 
+- [Client](reference/client.md)
 - Tasks
   - [RequestTask](reference/tasks/request_task.md)
 - Transformers
-  - [RequestTransformer]
+  - [RequestTransformer](reference/transformers/request_transformer.md)
+
+## Cookbooks
+
+- [Call a SOAP service and export the response](cookbooks/soap_call_and_export.md)
+- [Enrich a CSV file with a SOAP service](cookbooks/soap_enrich_csv.md)