Merge pull request #26 from clue-labs/internal

Mark all classes as final and all internal APIs as @internal

Author: clue

src/Client.php

@@ -3,19 +3,27 @@
 namespace Clue\React\Soap;
 
 use Clue\React\Buzz\Browser;
-use Exception;
-use Clue\React\Soap\Protocol\ClientEncoder;
 use Clue\React\Soap\Protocol\ClientDecoder;
+use Clue\React\Soap\Protocol\ClientEncoder;
 use Psr\Http\Message\ResponseInterface;
 use React\Promise\Deferred;
 
-class Client
+final class Client
 {
     private $wsdl;
     private $browser;
     private $encoder;
     private $decoder;
 
+    /**
+     * [internal] Instantiate new SOAP client, see Factory instead
+     *
+     * @param string $wsdl
+     * @param Browser $browser
+     * @param ClientEncoder $encoder
+     * @param ClientDecoder $decoder
+     * @internal
+     */
     public function __construct($wsdl, Browser $browser, ClientEncoder $encoder = null, ClientDecoder $decoder = null)
     {
         if ($encoder === null) {
@@ -43,21 +51,20 @@ public function soapCall($name, $args)
         }
 
         return $this->browser->send($request)->then(
-            array($this, 'handleResponse'),
-            array($this, 'handleError')
+            array($this, 'handleResponse')
         );
     }
 
+    /**
+     * @param ResponseInterface $response
+     * @return mixed
+     * @internal
+     */
     public function handleResponse(ResponseInterface $response)
     {
         return $this->decoder->decode((string)$response->getBody());
     }
 
-    public function handleError(Exception $error)
-    {
-        throw $error;
-    }
-
     public function getFunctions()
     {
         return $this->encoder->__getFunctions();
@@ -87,7 +94,7 @@ public function getTypes()
      *
      * @param string|int $function
      * @return string
-     * @throws SoapFault if given function does not exist
+     * @throws \SoapFault if given function does not exist
      * @see self::getFunctions()
      */
     public function getLocation($function)

src/Factory.php

@@ -6,7 +6,7 @@
 use Clue\React\Buzz\Browser;
 use Psr\Http\Message\ResponseInterface;
 
-class Factory
+final class Factory
 {
     private $loop;
     private $browser;

src/Protocol/ClientDecoder.php

@@ -4,7 +4,10 @@
 
 use \SoapClient;
 
-class ClientDecoder extends SoapClient
+/**
+ * @internal
+ */
+final class ClientDecoder extends SoapClient
 {
     private $response = null;
 
@@ -15,6 +18,13 @@ public function __construct()
         parent::__construct(null, array('location' => '1', 'uri' => '2'));
     }
 
+    /**
+     * Decodes the SOAP response / return value from the given SOAP envelope (HTTP response body)
+     *
+     * @param string $response
+     * @return mixed
+     * @throws \SoapFault if response indicates a fault (error condition) or is invalid
+     */
     public function decode($response)
     {
         // temporarily save response internally for further processing
@@ -28,6 +38,16 @@ public function decode($response)
         return $ret;
     }
 
+    /**
+     * Overwrites the internal request logic to parse the response
+     *
+     * By overwriting this method, we can skip the actual request sending logic
+     * and still use the internal parsing logic by injecting the response as
+     * the return code in this method. This will implicitly be invoked by the
+     * call to `pseudoCall()` in the above `decode()` method.
+     *
+     * @see SoapClient::__doRequest()
+     */
     public function __doRequest($request, $location, $action, $version, $one_way = 0)
     {
         // the actual result doesn't actually matter, just return the given result

src/Protocol/ClientEncoder.php

@@ -5,10 +5,21 @@
 use \SoapClient;
 use RingCentral\Psr7\Request;
 
-class ClientEncoder extends SoapClient
+/**
+ * @internal
+ */
+final class ClientEncoder extends SoapClient
 {
     private $request = null;
 
+    /**
+     * Encodes the given RPC function name and arguments as a SOAP request
+     *
+     * @param string $name
+     * @param array $args
+     * @return Request
+     * @throws \SoapFault if request is invalid according to WSDL
+     */
     public function encode($name, $args)
     {
         $this->__soapCall($name, $args);
@@ -19,6 +30,18 @@ public function encode($name, $args)
         return $request;
     }
 
+    /**
+     * Overwrites the internal request logic to build the request message
+     *
+     * By overwriting this method, we can skip the actual request sending logic
+     * and still use the internal request serializing logic by accessing the
+     * given `$request` parameter and building our custom request object from
+     * it. We skip/ignore its parsing logic by returing an empty response here.
+     * This will implicitly be invoked by the call to `__soapCall()` in the
+     * above `encode()` method.
+     *
+     * @see SoapClient::__doRequest()
+     */
     public function __doRequest($request, $location, $action, $version, $one_way = 0)
     {
         $this->request = new Request(

src/Proxy.php

@@ -2,8 +2,10 @@
 
 namespace Clue\React\Soap;
 
-class Proxy
+final class Proxy
 {
+    private $client;
+
     public function __construct(Client $client)
     {
         $this->client = $client;

tests/Protocol/ClientDecoderTest.php

@@ -0,0 +1,16 @@
+<?php
+
+use Clue\React\Soap\Protocol\ClientDecoder;
+use PHPUnit\Framework\TestCase;
+
+class ClientDecoderTest extends TestCase
+{
+    /**
+     * @expectedException SoapFault
+     */
+    public function testDecodeThrowsSoapFaultForInvalidResponse()
+    {
+        $decoder = new ClientDecoder();
+        $decoder->decode('invalid');
+    }
+}

tests/Protocol/ClientEncoderTest.php

@@ -0,0 +1,44 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+use Clue\React\Soap\Protocol\ClientEncoder;
+use Psr\Http\Message\RequestInterface;
+
+class ClientEncoderTest extends TestCase
+{
+    public function testEncodeCreatesRequestForNonWsdlRpcFunction()
+    {
+        $encoder = new ClientEncoder(null, array('location' => 'http://example.com/soap', 'uri' => 'demo'));
+
+        $request = $encoder->encode('add', array('first' => 10, 'second' => 20));
+
+        $this->assertTrue($request instanceof RequestInterface);
+        $this->assertSame('POST', $request->getMethod());
+        $this->assertSame('http://example.com/soap', (string)$request->getUri());
+        $this->assertSame('text/xml; charset=utf-8', $request->getHeaderLine('Content-Type'));
+    }
+
+    /**
+     * @expectedException SoapFault
+     */
+    public function testConstructorThrowsWhenUrlIsInvalid()
+    {
+        if (extension_loaded('xdebug')) {
+            $this->markTestSkipped('Invalid WSDL causes a fatal error when ext-xdebug is loaded');
+        }
+
+        new ClientEncoder('invalid');
+    }
+
+    /**
+     * @expectedException SoapFault
+     */
+    public function testConstructorThrowsWhenNonWsdlDoesNotDefineLocationAndUri()
+    {
+        if (extension_loaded('xdebug')) {
+            $this->markTestSkipped('Invalid non-WSDL mode causes a fatal error when ext-xdebug is loaded');
+        }
+
+        new ClientEncoder(null);
+    }
+}