doc(v1): reworked testing(fake), commands & index documentation (#17)

Author: CodeDredd

docs/commands.md

@@ -0,0 +1,32 @@
+# :fontawesome-solid-journal-whills: **Commands**
+
+---
+Yes this package comes with some artisan commands to make soap a bit more enjoyable.
+
+---
+![alt text](https://forum.endeavouros.com/uploads/default/original/2X/5/55b7271051f1bfcdcafcfd56e6704dade6936e1f.png "Artisan Commands"){: style="height:auto;width:100%"}
+
+---
+## :fontawesome-brands-jedi-order: **Requirements**
+
+You need to install following package to use the code generation feature
+
+````bash
+composer require --dev laminas/laminas-code wsdl2phpgenerator/wsdl2phpgenerator
+````
+
+## :fontawesome-brands-jedi-order: **Overview**
+
+Command                            | Description
+---------------------------------- | -------------
+`php artisan soap:make:client`     | Create a customized client by wsdl or config name
+`php artisan soap:make:validation` | Create one or all validation classes by wsdl or config name
+
+## :fontawesome-brands-jedi-order: **Configuration**
+
+If you have published the configuration file then you have some options for the code generation.
+
+Config             | Default            | Description
+------------------ | ------------------ | -----------
+``code.path``      | `app_path('Soap')` | Define where the generated Code should be saved in your project
+``code.namespace`` | `App\\Soap`        | Define the namespace of the generated Code 

docs/commands/make-client.md

@@ -1,5 +1,33 @@
-# Introduction
+# :fontawesome-solid-journal-whills: **Get started**
 
+---
 This package provides an expressive, minimal API around the [Soap Client from Phpro](https://github.com/phpro/soap-client), allowing you to quickly make outgoing SOAP requests to communicate with other web applications.
+
+---
+![alt text](https://www.netways.de/wp-content/uploads/2009/12/6a00d8341d3df553ef012875f312f9970c-800wi.jpg "Laravel Soap"){: style="height:auto;width:100%"}
+
+---
+## :fontawesome-brands-jedi-order: **Introduction**
+
 It is using [HTTPplug](http://httplug.io/) as handler with [Guzzle](https://github.com/php-http/guzzle6-adapter) as client.
 Some code is based/copied on/from [Laravel Http wrapper](https://github.com/illuminate/http). Thanks for inspiration :-)
+
+## :fontawesome-brands-jedi-order: **Installation**
+
+!!! abstract "Package"
+    Execute the following command to get the latest version of the package:
+    ````bash
+    composer require codedredd/laravel-soap
+    ````
+
+!!! info "Configuration"
+    Publish Configuration
+    ```bash
+    php artisan vendor:publish --provider "CodeDredd\Soap\SoapServiceProvider"
+    ```
+
+!!! warning "Code generation feature"
+    If you also want to use the code generation feature you have to install following packages:
+    ````bash
+    composer require --dev laminas/laminas-code wsdl2phpgenerator/wsdl2phpgenerator
+    ````

docs/commands/make-validation.md

@@ -1,88 +1,195 @@
 # :fontawesome-solid-journal-whills: **Testing**
 
-Many Laravel services provide functionality to help you easily and expressively write tests, and this SOAP wrapper is no exception.
+---
+Many Laravel services provide functionality to help you easily and expressively write tests, 
+and this SOAP wrapper is no exception.
 
+---
+![alt text](https://image.slidesharecdn.com/agilelessonsfromstarwarsapil17-170125183657/95/agile-lessons-to-learn-from-star-wars-15-638.jpg?cb=1485369462 "Testing"){: style="height:auto;width:100%"}
+
+---
 ## :fontawesome-brands-jedi-order: **Faking**
 
-The `Soap` facade's `fake` method allows you to instruct the SOAP client to return stubbed / dummy responses when requests are made.
+Include `#!php-inline use CodeDredd\Soap\Facades\Soap` in your testing class.
+The `Soap` facade's `fake` method allows you to instruct the SOAP client to return stubbed / dummy responses 
+when requests are made.
+
+### :fontawesome-solid-jedi: ***fake***
+
+> Intercepts request with possible given responses
+
+!!! info ""
+    - **`Method`** : `#!php-inline function fake($callback = null)`
+    - **`Param`** : `#!php-inline callable|array $callback`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\SoapFactory`
+
+!!! example "Examples with Soap::response"
+    === "simple"
+        For returning empty `200` status code responses for every request, you may call the `fake` method with no arguments
+        ``` php-inline
+        Soap::fake();
+        ```
+    === "with arguments"
+        You may pass an array to the `fake` method. The array's keys should represent ACTION patterns that you wish to fake and their associated responses. The `*` character may be used as a wildcard character. You may use the `response` method to construct stub / fake responses for these endpoints
+        ```` php-inline
+        Soap::fake([
+            // Stub a JSON response for all Get_ actions...
+            'Get_*' => Soap::response(['foo' => 'bar'], 200, ['Headers']),
+    
+            // Stub a string response for Submit_User action
+            'Submit_User' => Soap::response('Hello World', 200, ['Headers']),
+        ]);
+        ````
+        
+        !!! warning "Difference between Laravel Http"
+            The difference between Laravels HTTP wrapper is the fact that actions which are not defined in fake are also faked with a default 200 response!
+            
+    === "overwrite default response"
+        ``` php-inline
+        Soap::fake([
+            // Stub a JSON response for all Get_ actions...
+            'Get_*' => Soap::response(['foo' => 'bar'], 200, ['Headers']),
+    
+            // Stub a string response for all other actions
+            '*' => Soap::response('Hello World', 200, ['Headers']),
+        ]);
+        ```
+    === "with callback"
+        If you require more complicated logic to determine what responses to return for certain endpoints, you may pass a callback to the `fake` method. This callback will receive an instance of `CodeDredd\Soap\Client\Request` and should return a response instance:
+        ``` php-inline
+        Soap::fake(function ($request) {
+            return Soap::response('Hello World', 200);
+        });
+        ```
+
+!!! example "Examples with Soap::sequence"
+    === "simple"
+        Sometimes you may need to specify that a single ACTION should return a series of fake responses in a specific order. You may accomplish this by using the `Soap::sequence` method to build the responses:
+        ```` php-inline
+        Soap::fake([
+            // Stub a series of responses for Get_* actions...
+            'Get_*' => Soap::sequence()
+                ->push('Hello World')
+                ->push(['foo' => 'bar'])
+                ->pushStatus(404)
+        ]);
+        ````
+        
+        !!! warning "Throws exception if empty"
+            When all of the responses in a response sequence have been consumed, any further requests will cause the response sequence to throw an exception!
+            
+    === "wtih whenEmpty"
+        If you would like to specify a default response that should be returned when a sequence is empty, you may use the `whenEmpty` method
+        ``` php-inline
+        Soap::fake([
+            // Stub a series of responses for Get_* actions...
+            'Get_*' => Soap::sequence()
+                ->push('Hello World')
+                ->push(['foo' => 'bar'])
+                ->whenEmpty(Soap::response())
+        ]);
+        ```
+
+### :fontawesome-solid-jedi: ***response***
 
-### Simple Fake
-For example, to instruct the SOAP client to return empty, `200` status code responses for every request, you may call the `fake` method with no arguments:
+> Create a new response instance for use during stubbing (for fake responses)
 
-    use CodeDredd\Soap\Facades\Soap;
+!!! info ""
 
-    Soap::fake();
+    - **`Method`** : `#!php-inline static function response($body = null, $status = 200, $headers = [])`
+    - **`Param`** : `#!php-inline array|string|null $body`
+    - **`Param`** : `#!php-inline int $status`
+    - **`Param`** : `#!php-inline array $headers`
+    - **`Return`** : `#!php-inline \GuzzleHttp\Promise\PromiseInterface`
 
-    $response = Soap::baseWsdl(...)->call(...);
+!!! warning "When `$body` is string"
+    One important notice. Because a SOAP API doesn't return a single string value every response with only a string in the body is wrapped in an array with key `response`.
+    
+        [
+            'response' => 'Hello World'
+        ]
 
-### Faking Specific URLs
+### :fontawesome-solid-jedi: ***sequence***
 
-Alternatively, you may pass an array to the `fake` method. The array's keys should represent ACTION patterns that you wish to fake and their associated responses. The `*` character may be used as a wildcard character. You may use the `response` method to construct stub / fake responses for these endpoints:
-The difference between Laravels HTTP wrapper is the fact that actions which are not defined in fake are also faked with a default 200 response!
-Also a faked response status code is always 200 if you define it in the range between 200 and 400. Status codes 400 and greater are correct responded.
+> Get an invokable object that returns a sequence of responses in order for use during stubbing
 
-    Soap::fake([
-        // Stub a JSON response for all Get_ actions...
-        'Get_*' => Soap::response(['foo' => 'bar'], 200, ['Headers']),
+!!! info ""
+    - **`Method`** : `#!php-inline function sequence(array $responses = [])`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
+    
+#### :fontawesome-brands-galactic-republic: ***push***
 
-        // Stub a string response for Submit_User action
-        'Submit_User' => Soap::response('Hello World', 200, ['Headers']),
-    ]);
+> Push a response to the sequence.
 
-If you would like to overwrite the fallback ACTION pattern that will stub all unmatched URLs, you may use a single `*` character:
+!!! info ""
+    - **`Method`** : `#!php-inline function push($body = '', int $status = 200, array $headers = [])`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
 
-    Soap::fake([
-        // Stub a JSON response for all Get_ actions...
-        'Get_*' => Soap::response(['foo' => 'bar'], 200, ['Headers']),
+#### :fontawesome-brands-galactic-republic: ***pushResponse***
 
-        // Stub a string response for all other actions
-        '*' => Soap::response('Hello World', 200, ['Headers']),
-    ]);
+> Push a response to the sequence.
 
-One important notice. Because a SOAP API doesn't return only string every response with only a string in the body will be formatted to an array:
+!!! info ""
+    - **`Method`** : `#!php-inline function pushResponse($response)`
+    - **`Param`** : `#!php-inline \GuzzleHttp\Promise\PromiseInterface|\Closure $response`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
+    
+#### :fontawesome-brands-galactic-republic: ***pushStatus***
 
-    //For above example
-    [
-        'response' => 'Hello World'
-    ]
+> Push a response with the given status code to the sequence.
 
-### Faking Response Sequences
+!!! info ""
+    - **`Method`** : `#!php-inline function pushStatus(string $filePath, int $status = 200, array $headers = [])`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
+    
+#### :fontawesome-brands-galactic-republic: ***dontFailWhenEmpty***
 
-Sometimes you may need to specify that a single ACTION should return a series of fake responses in a specific order. You may accomplish this by using the `Soap::sequence` method to build the responses:
+> Make the sequence return a default response when it is empty.
 
-    Soap::fake([
-        // Stub a series of responses for Get_* actions...
-        'Get_*' => Soap::sequence()
-            ->push('Hello World')
-            ->push(['foo' => 'bar'])
-            ->pushStatus(404)
-    ]);
+!!! info ""
+    - **`Method`** : `#!php-inline function dontFailWhenEmpty()`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
+    
+#### :fontawesome-brands-galactic-republic: ***whenEmpty***
 
-When all of the responses in a response sequence have been consumed, any further requests will cause the response sequence to throw an exception. If you would like to specify a default response that should be returned when a sequence is empty, you may use the `whenEmpty` method:
+> Make the sequence return a custom default response when it is empty.
 
-    Soap::fake([
-        // Stub a series of responses for Get_* actions...
-        'Get_*' => Soap::sequence()
-            ->push('Hello World')
-            ->push(['foo' => 'bar'])
-            ->whenEmpty(Soap::response())
-    ]);
+!!! info ""
+    - **`Method`** : `#!php-inline function whenEmpty($response)`
+    - **`Param`** : `#!php-inline \GuzzleHttp\Promise\PromiseInterface|\Closure $response`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
+    
+#### :fontawesome-brands-galactic-republic: ***pushFile***
 
-If you would like to fake a sequence of responses but do not need to specify a specific ACTION pattern that should be faked, you may use the `Soap::fakeSequence` method:
+> Push response with the contents of a file as the body to the sequence.
 
-    Soap::fakeSequence()
-        ->push('Hello World')
-        ->whenEmpty(Soap::response());
+!!! info ""
+    - **`Method`** : `#!php-inline function pushFile(int $status = 200, array $headers = [])`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
 
-### Fake Callback
+### :fontawesome-solid-jedi: ***fakeSequence***
 
-If you require more complicated logic to determine what responses to return for certain endpoints, you may pass a callback to the `fake` method. This callback will receive an instance of `CodeDredd\Soap\Client\Request` and should return a response instance:
+If you would like to fake a sequence of responses but do not need to specify a specific ACTION pattern that should be faked, you may use the `Soap::fakeSequence` method.
 
-    Soap::fake(function ($request) {
-        return Soap::response('Hello World', 200);
-    });
+> Register a response sequence for the given URL pattern.
 
-------------------------
+!!! info ""
+    - **`Method`** : `#!php-inline function fakeSequence(string $url = '*')`
+    - **`Return`** : `#!php-inline \CodeDredd\Soap\Client\ResponseSequence`
+    
+!!! example "Example"
+    ``` php-inline
+    Soap::fakeSequence()
+        ->push('Hello World')
+        ->whenEmpty(Soap::response());
+    ```
+    
+!!! tip "Tip"
+    ``fakeSequence`` has the same methods as [`Soap::response`](#response).
+    So in most cases `fakeSequence` will be the better choice to fake response because its an easier and shorter
+    way to define fake responses.
+
+---
 
 ## :fontawesome-brands-jedi-order: **Asserts**