Merge pull request #56 from SimonFrings/updates

Simplify usage by updating to new default loop and making Browser optional
clue · Aug 13, 2021 · e802f94 · e802f94
2 parents 602149d + c1064cb
commit e802f94
Show file tree

Hide file tree

Showing 7 changed files with 68 additions and 83 deletions.
diff --git a/README.md b/README.md
@@ -67,8 +67,11 @@ Once [installed](#install), you can use the following code to query an example
 web service via SOAP:
 
 ```php
-$loop = React\EventLoop\Factory::create();
-$browser = new React\Http\Browser($loop);
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+$browser = new React\Http\Browser();
 $wsdl = 'http://example.com/demo.wsdl';
 
 $browser->get($wsdl)->then(function (Psr\Http\Message\ResponseInterface $response) use ($browser) {
@@ -79,8 +82,6 @@ $browser->get($wsdl)->then(function (Psr\Http\Message\ResponseInterface $respons
         var_dump('Result', $result);
     });
 });
-
-$loop->run();
 ```
 
 See also the [examples](examples).
@@ -90,30 +91,26 @@ See also the [examples](examples).
 ### Client
 
 The `Client` class is responsible for communication with the remote SOAP
-WebService server.
-
-It requires a [`Browser`](https://github.com/reactphp/http#browser) object
-bound to the main [`EventLoop`](https://github.com/reactphp/event-loop#usage)
-in order to handle async requests, the WSDL file contents and an optional
+WebService server. It requires the WSDL file contents and an optional
 array of SOAP options:
 
 ```php
-$loop = React\EventLoop\Factory::create();
-$browser = new React\Http\Browser($loop);
-
 $wsdl = '<?xml …';
 $options = array();
 
-$client = new Clue\React\Soap\Client($browser, $wsdl, $options);
+$client = new Clue\React\Soap\Client(null, $wsdl, $options);
 ```
 
+This class takes an optional `Browser|null $browser` parameter that can be used to
+pass the browser instance to use for this object.
 If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
 proxy servers etc.), you can explicitly pass a custom instance of the
 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
-to the [`Browser`](https://github.com/reactphp/http#browser) instance:
+to the [`Browser`](https://github.com/reactphp/http#browser) instance
+and pass it as an additional argument to the `Client` like this:
 
 ```php
-$connector = new React\Socket\Connector($loop, array(
+$connector = new React\Socket\Connector(array(
     'dns' => '127.0.0.1',
     'tcp' => array(
         'bindto' => '192.168.10.1:0'
@@ -124,7 +121,7 @@ $connector = new React\Socket\Connector($loop, array(
     )
 ));
 
-$browser = new React\Http\Browser($loop, $connector);
+$browser = new React\Http\Browser($connector);
 $client = new Clue\React\Soap\Client($browser, $wsdl);
 ```
 
@@ -134,7 +131,7 @@ you to use local WSDL files, WSDL files from a cache or the most common form,
 downloading the WSDL file contents from an URL through the `Browser`:
 
 ```php
-$browser = new React\Http\Browser($loop);
+$browser = new React\Http\Browser();
 
 $browser->get($url)->then(
     function (Psr\Http\Message\ResponseInterface $response) use ($browser) {
@@ -155,7 +152,7 @@ parsed, this will throw a `SoapFault`:
 
 ```php
 try {
-    $client = new Clue\React\Soap\Client($browser, $wsdl);
+    $client = new Clue\React\Soap\Client(null, $wsdl);
 } catch (SoapFault $e) {
     echo 'Error: ' . $e->getMessage() . PHP_EOL;
 }
@@ -179,7 +176,7 @@ the URL of the SOAP server to send the request to, and `uri` is the target
 namespace of the SOAP service:
 
 ```php
-$client = new Clue\React\Soap\Client($browser, null, array(
+$client = new Clue\React\Soap\Client(null, null, array(
     'location' => 'http://example.com',
     'uri' => 'http://ping.example.com',
 ));
@@ -189,7 +186,7 @@ Similarly, if working in WSDL mode, the `location` option can be used to
 explicitly overwrite the URL of the SOAP server to send the request to:
 
 ```php
-$client = new Clue\React\Soap\Client($browser, $wsdl, array(
+$client = new Clue\React\Soap\Client(null, $wsdl, array(
     'location' => 'http://example.com'
 ));
 ```
@@ -198,7 +195,7 @@ You can use the `soap_version` option to change from the default SOAP 1.1 to
 use SOAP 1.2 instead:
 
 ```php
-$client = new Clue\React\Soap\Client($browser, $wsdl, array(
+$client = new Clue\React\Soap\Client(null, $wsdl, array(
     'soap_version' => SOAP_1_2
 ));
 ```
@@ -207,7 +204,7 @@ You can use the `classmap` option to map certain WSDL types to PHP classes
 like this:
 
 ```php
-$client = new Clue\React\Soap\Client($browser, $wsdl, array(
+$client = new Clue\React\Soap\Client(null, $wsdl, array(
     'classmap' => array(
         'getBankResponseType' => BankResponse::class
     )
@@ -366,7 +363,7 @@ clean up any underlying resources.
 ```php
 $promise = $proxy->demo();
 
-$loop->addTimer(2.0, function () use ($promise) {
+Loop::addTimer(2.0, function () use ($promise) {
     $promise->cancel();
 });
 ```
@@ -389,7 +386,7 @@ pass the timeout to the [underlying `Browser`](https://github.com/reactphp/http#
 like this:
 
 ```php
-$browser = new React\Http\Browser($loop);
+$browser = new React\Http\Browser();
 $browser = $browser->withTimeout(10.0);
 
 $client = new Clue\React\Soap\Client($browser, $wsdl);

diff --git a/composer.json b/composer.json
@@ -18,7 +18,7 @@
     },
     "require": {
         "php": ">=7.1",
-        "react/http": "^1.0",
+        "react/http": "^1.5",
         "react/promise": "^2.1 || ^1.2",
         "ext-soap": "*"
     },

diff --git a/examples/01-client-blz-wsdl.php b/examples/01-client-blz-wsdl.php
@@ -2,8 +2,7 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$loop = React\EventLoop\Factory::create();
-$browser = new React\Http\Browser($loop);
+$browser = new React\Http\Browser();
 
 $blz = isset($argv[1]) ? $argv[1] : '12070000';
 
@@ -21,5 +20,3 @@ function (Exception $e) {
         }
     );
 });
-
-$loop->run();
diff --git a/examples/02-client-blz-non-wsdl.php b/examples/02-client-blz-non-wsdl.php
@@ -2,12 +2,9 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$loop = React\EventLoop\Factory::create();
-$browser = new React\Http\Browser($loop);
-
 $blz = isset($argv[1]) ? $argv[1] : '12070000';
 
-$client = new Clue\React\Soap\Client($browser, null, array(
+$client = new Clue\React\Soap\Client(null, null, array(
     'location' => 'http://www.thomas-bayer.com/axis2/services/BLZService',
     'uri' => 'http://thomas-bayer.com/blz/',
     'use' => SOAP_LITERAL
@@ -23,5 +20,3 @@ function (Exception $e) {
         echo 'ERROR: ' . $e->getMessage() . PHP_EOL;
     }
 );
-
-$loop->run();
diff --git a/examples/11-wsdl-info.php b/examples/11-wsdl-info.php
@@ -2,8 +2,7 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$loop = React\EventLoop\Factory::create();
-$browser = new React\Http\Browser($loop);
+$browser = new React\Http\Browser();
 
 $wsdl = isset($argv[1]) ? $argv[1] : 'http://www.thomas-bayer.com/axis2/services/BLZService?wsdl';
 
@@ -21,5 +20,3 @@ function (Exception $e) {
         echo 'Error: ' . $e->getMessage() . PHP_EOL;
     }
 );
-
-$loop->run();
diff --git a/src/Client.php b/src/Client.php
@@ -11,30 +11,26 @@
 
 /**
  * The `Client` class is responsible for communication with the remote SOAP
- * WebService server.
- *
- * It requires a [`Browser`](https://github.com/reactphp/http#browser) object
- * bound to the main [`EventLoop`](https://github.com/reactphp/event-loop#usage)
- * in order to handle async requests, the WSDL file contents and an optional
+ * WebService server. It requires the WSDL file contents and an optional
  * array of SOAP options:
  *
  * ```php
- * $loop = React\EventLoop\Factory::create();
- * $browser = new React\Http\Browser($loop);
- *
  * $wsdl = '<?xml …';
  * $options = array();
  *
- * $client = new Clue\React\Soap\Client($browser, $wsdl, $options);
+ * $client = new Clue\React\Soap\Client(null, $wsdl, $options);
  * ```
  *
+ * This class takes an optional `Browser|null $browser` parameter that can be used to
+ * pass the browser instance to use for this object.
  * If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
  * proxy servers etc.), you can explicitly pass a custom instance of the
  * [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
- * to the [`Browser`](https://github.com/clue/reactphp/http#browser) instance:
+ * to the [`Browser`](https://github.com/reactphp/http#browser) instance
+ * and pass it as an additional argument to the `Client` like this:
  *
  * ```php
- * $connector = new React\Socket\Connector($loop, array(
+ * $connector = new React\Socket\Connector(array(
  *     'dns' => '127.0.0.1',
  *     'tcp' => array(
  *         'bindto' => '192.168.10.1:0'
@@ -45,7 +41,7 @@
  *     )
  * ));
  *
- * $browser = new React\Http\Browser($loop, $connector);
+ * $browser = new React\Http\Browser($connector);
  * $client = new Clue\React\Soap\Client($browser, $wsdl);
  * ```
  *
@@ -55,7 +51,7 @@
  * downloading the WSDL file contents from an URL through the `Browser`:
  *
  * ```php
- * $browser = new React\Http\Browser($loop);
+ * $browser = new React\Http\Browser();
  *
  * $browser->get($url)->then(
  *     function (Psr\Http\Message\ResponseInterface $response) use ($browser) {
@@ -76,7 +72,7 @@
  *
  * ```php
  * try {
- *     $client = new Clue\React\Soap\Client($browser, $wsdl);
+ *     $client = new Clue\React\Soap\Client(null, $wsdl);
  * } catch (SoapFault $e) {
  *     echo 'Error: ' . $e->getMessage() . PHP_EOL;
  * }
@@ -100,7 +96,7 @@
  * namespace of the SOAP service:
  *
  * ```php
- * $client = new Clue\React\Soap\Client($browser, null, array(
+ * $client = new Clue\React\Soap\Client(null, null, array(
  *     'location' => 'http://example.com',
  *     'uri' => 'http://ping.example.com',
  * ));
@@ -110,7 +106,7 @@
  * explicitly overwrite the URL of the SOAP server to send the request to:
  *
  * ```php
- * $client = new Clue\React\Soap\Client($browser, $wsdl, array(
+ * $client = new Clue\React\Soap\Client(null, $wsdl, array(
  *     'location' => 'http://example.com'
  * ));
  * ```
@@ -119,7 +115,7 @@
  * use SOAP 1.2 instead:
  *
  * ```php
- * $client = new Clue\React\Soap\Client($browser, $wsdl, array(
+ * $client = new Clue\React\Soap\Client(null, $wsdl, array(
  *     'soap_version' => SOAP_1_2
  * ));
  * ```
@@ -128,7 +124,7 @@
  * like this:
  *
  * ```php
- * $client = new Clue\React\Soap\Client($browser, $wsdl, array(
+ * $client = new Clue\React\Soap\Client(null, $wsdl, array(
  *     'classmap' => array(
  *         'getBankResponseType' => BankResponse::class
  *     )
@@ -146,29 +142,32 @@
  */
 class Client
 {
+    /** @var Browser */
     private $browser;
+
     private $encoder;
     private $decoder;
 
     /**
      * Instantiate a new SOAP client for the given WSDL contents.
      *
-     * @param Browser     $browser
-     * @param string|null $wsdlContents
-     * @param array       $options
+     * @param ?Browser $browser
+     * @param ?string  $wsdlContents
+     * @param ?array   $options
      */
-    public function __construct(Browser $browser, ?string $wsdlContents, array $options = array())
+    public function __construct(?Browser $browser, ?string $wsdlContents, array $options = array())
     {
         $wsdl = $wsdlContents !== null ? 'data://text/plain;base64,' . base64_encode($wsdlContents) : null;
 
+        $this->browser = $browser ?? new Browser();
+
         // Accept HTTP responses with error status codes as valid responses.
         // This is done in order to process these error responses through the normal SOAP decoder.
         // Additionally, we explicitly limit number of redirects to zero because following redirects makes little sense
         // because it transforms the POST request to a GET one and hence loses the SOAP request body.
-        $browser = $browser->withRejectErrorResponse(false);
-        $browser = $browser->withFollowRedirects(0);
+        $this->browser = $this->browser->withRejectErrorResponse(false);
+        $this->browser = $this->browser->withFollowRedirects(0);
 
-        $this->browser = $browser;
         $this->encoder = new ClientEncoder($wsdl, $options);
         $this->decoder = new ClientDecoder($wsdl, $options);
     }