diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..ee4d20b --- /dev/null +++ b/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 diff --git a/docs/commands/make-client.md b/docs/commands/make-client.md deleted file mode 100644 index caf0066..0000000 --- a/docs/commands/make-client.md +++ /dev/null @@ -1,13 +0,0 @@ -# Make Client - -## Command - -````bash -php artisan soap:make:client -```` - -## Options - -### --dry-run - -Returns all code in console instead of saving in a file diff --git a/docs/commands/make-validation.md b/docs/commands/make-validation.md deleted file mode 100644 index cc9e3da..0000000 --- a/docs/commands/make-validation.md +++ /dev/null @@ -1,13 +0,0 @@ -# Make Validation - -## Command - -````bash -php artisan soap:make:validation -```` - -## Options - -### --dry-run - -Returns all code in console instead of saving in a file diff --git a/docs/commands/overview.md b/docs/commands/overview.md deleted file mode 100644 index f85cb33..0000000 --- a/docs/commands/overview.md +++ /dev/null @@ -1,29 +0,0 @@ -# Overview of Commands - -... better docs will come ;-) - -## Requirements - -You need to install following package to use the code generation feature - -````bash -composer require --dev laminas/laminas-code wsdl2phpgenerator/wsdl2phpgenerator -```` - -Here is a list of all available soap commands. - -## Commands - -Command | Description --------------------------------------------------------- | ------------- -[`php artisan soap:make:client`](make-client.md) | Create a customized client by wsdl or config name -[`php artisan soap:make:validation`](make-validation.md) | Create one or all validation classes by wsdl or config name - -## 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 diff --git a/docs/index.md b/docs/index.md index 26c2ae3..4fe56cc 100644 --- a/docs/index.md +++ b/docs/index.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 + ```` diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 5682977..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,15 +0,0 @@ -# Installation - -Execute the following command to get the latest version of the package: - - composer require codedredd/laravel-soap - -Publish Configuration - - php artisan vendor:publish --provider "CodeDredd\Soap\SoapServiceProvider" - -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 -```` diff --git a/docs/testing.md b/docs/testing.md index ddce1f1..f964452 100644 --- a/docs/testing.md +++ b/docs/testing.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** diff --git a/docs/testing/asserts.md b/docs/testing/asserts.md deleted file mode 100644 index 96d7f86..0000000 --- a/docs/testing/asserts.md +++ /dev/null @@ -1,63 +0,0 @@ -# Asserts - -When faking responses, you may occasionally wish to inspect the requests the client receives in order to make sure your application is sending the correct data or headers. You may accomplish this by calling the `Soap::assertSent` method after calling `Soap::fake`. - -## Overview - -### assertSent - -!!! info "" - - **`Method`** : `#!php-inline function assertSent(callable $callback)` - - **`Return`** : `#!php-inline void` - -!!! example "Examples" - === "simple" - ``` php-inline - Soap::assertSent(function($request){ - return $request->action() === 'YourAction' - }); - ``` - === "with arguments" - ``` php-inline - Soap::assertSent(function($request){ - return $request->action() === 'YourAction' && - $request->arguments() === ['argument' => 'value'] - }); - ``` - - -## Examples -The `assertSent` method accepts a callback which will be given an `CodeDredd\Soap\Client\Request` instance and should return a boolean value indicating if the request matches your expectations. In order for the test to pass, at least one request must have been issued matching the given expectations: - - Soap::fake(); - - Soap::withHeaders([ - 'X-First' => 'foo', - ])->baseWsdl('http://test.com/v1?wsdl') - ->call('Get_Users', [ - 'name' => 'CodeDredd' - ]); - - Soap::assertSent(function ($request) { - return $request->action() === 'Get_Users' && - $request->arguments() === ['name' => 'CodeDredd']; - }); - //Or shortcut - Soap::assertActionSent('Get_Users') - -If needed, you may assert that a specific request was not sent using the `assertNotSent` method: - - Soap::fake(); - - Soap::baseWsdl('http://test.com/v1?wsdl') - ->call('Get_Users'); - - Soap::assertNotSent(function (Request $request) { - return $request->action() === 'Get_Posts'; - }); - -Or, if you would like to assert that no requests were sent, you may use the `assertNothingSent` method: - - Soap::fake(); - - Soap::assertNothingSent(); diff --git a/docs/testing/faking.md b/docs/testing/faking.md deleted file mode 100644 index f3e5ce5..0000000 --- a/docs/testing/faking.md +++ /dev/null @@ -1,79 +0,0 @@ -# Faking - -Many Laravel services provide functionality to help you easily and expressively write tests, and this SOAP wrapper is no exception. The `Soap` facade's `fake` method allows you to instruct the SOAP client to return stubbed / dummy responses when requests are made. - -## 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: - - use CodeDredd\Soap\Facades\Soap; - - Soap::fake(); - - $response = Soap::baseWsdl(...)->call(...); - -## Faking Specific URLs - -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. - - 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']), - ]); - -If you would like to overwrite the fallback ACTION pattern that will stub all unmatched URLs, you may use a single `*` character: - - 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']), - ]); - -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: - - //For above example - [ - 'response' => 'Hello World' - ] - -## Faking Response Sequences - -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: - - Soap::fake([ - // Stub a series of responses for Get_* actions... - 'Get_*' => Soap::sequence() - ->push('Hello World') - ->push(['foo' => 'bar']) - ->pushStatus(404) - ]); - -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: - - Soap::fake([ - // Stub a series of responses for Get_* actions... - 'Get_*' => Soap::sequence() - ->push('Hello World') - ->push(['foo' => 'bar']) - ->whenEmpty(Soap::response()) - ]); - -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::fakeSequence() - ->push('Hello World') - ->whenEmpty(Soap::response()); - -## Fake 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: - - Soap::fake(function ($request) { - return Soap::response('Hello World', 200); - }); diff --git a/mkdocs.yml b/mkdocs.yml index 77417d0..4bf4876 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,22 +9,23 @@ repo_url: 'https://github.com/codedredd/laravel-soap' copyright: Copyright © 2020 - 2020 Gregor Becker nav: - - Introduction: 'index.md' - - Installation: 'installation.md' + - 'Get started': 'index.md' - Client: - Request: 'client/request.md' - Response: 'client/response.md' - authentication: 'client/authentication.md' - configuration: 'client/configuration.md' - - Commands: - - Overview: 'commands/overview.md' - - 'Make Client': 'commands/make-client.md' - - 'Make Validation': 'commands/make-validation.md' + - Commands: 'commands.md' - Testing: 'testing.md' theme: name: 'material' + language: 'en' + palette: + primary: 'cyan' + accent: 'deep orange' markdown_extensions: - admonition + - attr_list - codehilite: guess_lang: false - toc: