Merge pull request #23 from veewee/feature-middlewares

Feature middlewares

.phpspec/specification.tpl

@@ -0,0 +1,18 @@
+<?php
+
+namespace %namespace%;
+
+use PhpSpec\ObjectBehavior;
+use Prophecy\Argument;
+use %subject%;
+
+/**
+ * Class %name%
+ */
+class %name% extends ObjectBehavior
+{
+    function it_is_initializable()
+    {
+        $this->shouldHaveType(%subject_class%::class);
+    }
+}

.travis.yml

@@ -6,13 +6,12 @@ cache:
 
 matrix:
   include:
-    - php: 5.5
-    - php: 5.5
+    - php: 7.0
+    - php: 7.0
       env: DEPENDENCIES='low'
-    - php: 5.6
-    - php: 5.6
+    - php: 7.1
+    - php: 7.1
       env: DEPENDENCIES='low'
-    - php: 7.0
   fast_finish: true
 
 before_install:
@@ -22,6 +21,7 @@ before_install:
 install:
   - if [ "$DEPENDENCIES" != "low" ]; then travis_retry composer update --no-progress --profile --prefer-dist --no-scripts --no-interaction; fi;
   - if [ "$DEPENDENCIES" == "low" ]; then travis_retry composer update --no-progress --profile --prefer-lowest --no-scripts --no-interaction; fi;
+  - composer show
 
 script:
    - ./vendor/bin/grumphp run

README.md

@@ -47,6 +47,14 @@ It is important keep your code clean. This is why we added an event-listener to
  You can hook in at every important step of the SOAP flow.
  This way it is possible to add logging, caching and error handling with event subscribers. 
  Pretty cool right?!
+
+Implementing SOAP extensions is a real pain in the ass.
+ It forces you to overwrite core methods of the built-in SOAP client.
+ If you ever had to implement WSA or WSSE in SOAP, you know that there is something wrong in the core.
+ Therefore we made it easy for you to extend our SOAP client. 
+ You can specify which data transfer handler like e.g. Guzzle you want to use.
+ Depending on the selected handler, 
+ you can easily add support for SOAP extensions or advanced authentication through HTTP middlewares.
 
 Testing webservices is hard! 
  That is Why this package is fully compatible with [php-vcr](http://php-vcr.github.io/).
@@ -70,15 +78,27 @@ $ composer require phpro/soap-client
 1. [Create your own SOAP client.](docs/client.md)
 2. [Generate PHP classes based on SOAP types.](docs/cli/generate-types.md)
 3. [Generate a class map](docs/cli/generate-classmap.md)
-4. [Add type converters](docs/type-converter.md)
-5. [Listen to events](docs/events.md)
+4. [Use your SOAP client.](docs/usage.md)
+5. [Test your SOAP client.](docs/testing.md)
+
+
+## Advanced configuration
+
+- [Add type converters.](docs/type-converter.md)
+- [Listen to events.](docs/events.md)
   - [Logger plugin](docs/plugins/logger.md)
   - [Caching plugin](docs/plugins/caching.md)
-6. [Use your SOAP client.](docs/usage.md)
-7. [Test your SOAP client.](docs/testing.md)
+- [Specify your data transfer handler.](docs/handlers.md)
+  - [SoapHandle](docs/handlers.md#soaphandle)
+  - [GuzzleHandle](docs/handlers.md#guzzlehandle)
+- [Configure one or multiple HTTP middlewares.](docs/middlewares.md)
+  - [BasicAuthMiddleware](docs/middlewares.md#basicauthmiddleware)
+  - [NtlmMiddleware](docs/middlewares.md#ntlmmiddleware)
+  - [WsaMiddleware](docs/middlewares.md#wsamiddleware)
+  - [WsseMiddleware](docs/middlewares.md#wssemiddleware)
 
 
-## Customize the code generators
+## Customize the code generation
 
 - [Configuration](docs/code-generation/configuration.md)
 - [Specify generation `Rules`](docs/code-generation/rules.md)

composer.json

@@ -10,26 +10,38 @@
     }
   ],
   "require": {
-    "psr/log": "^1.0",
+    "php": "^7.0",
     "doctrine/collections": "~1.3",
-    "symfony/event-dispatcher": "~2.3|~3.0",
-    "symfony/console": "~2.3|~3.0",
-    "symfony/filesystem": "~2.3|~3.0",
-    "symfony/process": "~2.3|~3.0",
-    "zendframework/zend-code": "^3.0.4"
+    "http-interop/http-factory": "^0.2.0",
+    "psr/http-message": "^1.0",
+    "psr/log": "^1.0",
+    "symfony/console": "~2.8|~3.0",
+    "symfony/event-dispatcher": "~2.8|~3.0",
+    "symfony/filesystem": "~2.8|~3.0",
+    "symfony/process": "~2.8|~3.0",
+    "zendframework/zend-code": "^3.0.4",
+    "zendframework/zend-diactoros": "^1.3"
   },
   "require-dev": {
-    "phpro/grumphp": "~0.9",
-    "squizlabs/php_codesniffer": "~2.6",
-    "phpspec/phpspec": "~2.5",
+    "guzzlehttp/guzzle": "^6.2",
+    "http-interop/http-factory-guzzle": "0.1.0",
+    "ocramius/proxy-manager": "^2.0.2",
+    "ocramius/package-versions": "^1.1.2",
+    "php-vcr/php-vcr": "^1.3.2",
+    "php-vcr/phpunit-testlistener-vcr": "^2.0",
+    "phpro/grumphp": "~0.11",
+    "phpspec/phpspec": "~3.2",
     "phpspec/prophecy": "~1.6",
-    "phpunit/phpunit": "~4.8",
-    "php-vcr/php-vcr": "^1.2.8",
-    "php-vcr/phpunit-testlistener-vcr": "^1.1.7"
+    "phpunit/phpunit": "~5.0",
+    "robrichards/wse-php": "^2.0",
+    "squizlabs/php_codesniffer": "~2.7"
   },
   "suggest": {
     "doctrine/common": "For caching SOAP responses",
-    "monolog/monolog": "For logging SOAP transactions"
+    "guzzlehttp/guzzle": "For requestng SOAP through Guzzle",
+    "http-interop/http-factory-guzzle": "For requestng SOAP through Guzzle",
+    "monolog/monolog": "For logging SOAP transactions",
+    "robrichards/wse-php": "If you want to use the WSA or WSSE middleware"
   },
   "autoload": {
     "psr-0": {
@@ -41,5 +53,8 @@
       "PhproTest\\SoapClient\\": "test/"
     }
   },
-  "bin": ["bin/soap-client"]
+  "bin": ["bin/soap-client"],
+  "config": {
+    "sort-packages": true
+  }
 }

docs/client.md

@@ -11,7 +11,7 @@ class YourClient extends Client
      * @param RequestInterface $request
      *
      * @return ResultInterface
-     * @throws \SoapFault
+     * @throws \Phpro\SoapClient\Exception\SoapException
      */
     public function helloWorld(RequestInterface $request)
     {
@@ -31,6 +31,9 @@ The methods of the class are explicitly defined and have explicit parameters and
  The `ResultProviderInterface` can be used if the response type is wrapping a `ResultInterface`.
  The `call` method will initailize the SOAP call and trigger the subscribed event listeners.
 
+As you can see, we've normalized the exception. Our SOAP client will always throw a custom `SoapException`.
+ This is to make it possible to use multiple different handlers which don't always throw a `SoapFault`.
+
 
 ## My SOAP service does not work with Request / Response objects.
 

docs/handlers.md

@@ -0,0 +1,52 @@
+# Use your preferred data transfer layer with Handlers
+
+The build-in SOAP client doesn't support extensions by default.
+To overcome this problem, you are forced to overwrite the `__doRequest()` method.
+By doing this, your code will be tied to the SoapClient which makes it hard to test and to reuse the logic.
+
+This package contains a handler system which allows you to get control over the HTTP layer of the soap client.
+The handler system makes it possible to make changes to the request and the response before sending it to the server. 
+
+Here is a list of built-in handlers:
+
+- [SoapHandle](#soaphandle)
+- [GuzzleHandle](#guzzlehandle)
+
+
+## SoapHandle
+
+*Features: LastRequestInfoCollector*
+
+The SoapHandle is used by default and works with the built-in `__doRequest()` method.
+This Handle is not configurable and can be used for soap implementations which do not use extensions.
+It is activated by default to get you going as quick as posile.
+
+**Configuration**
+```php
+$clientBuilder = new ClientBuilder($clientFactory, $wsdl, $soapOptions);
+$client = $clientBuilder->build();
+```
+
+
+## GuzzleHandle
+
+*Features: LastRequestInfoCollector, MiddlewareSupporting*
+
+With this handler it is easy to get in control about the HTTP layer of the SOAP client.
+You can specify one or multiple middlewares that are being applied on your guzzle client.
+This makes it possible to manipulate the request and response objects so that you can get full control.
+
+This handler is based on middlewares which are applied to your guzzle client.
+[You can read more about middlewares in this section.](middlewares.md)
+
+**Dependencies**
+```sh
+composer require guzzlehttp/guzzle:^6.2 http-interop/http-factory-guzzle:^0.1.0
+```
+
+**Configuration**
+```php
+$clientBuilder = new ClientBuilder($clientFactory, $wsdl, $soapOptions);
+$clientBuilder->withHandler(GuzzleHandle::createForClient($guzzleClient));
+$client = $clientBuilder->build();
+```