Add examples

Author: SimonFrings

README.md

@@ -136,6 +136,8 @@ try {
 }
 ```
 
+See also the [examples](examples/).
+
 If no `$timeout` argument is given and the promise stays pending, then this
 will potentially wait/block forever until the promise is settled.
 
@@ -160,6 +162,8 @@ $firstResult = Block\awaitAny($promises, $loop, $timeout);
 echo 'First result: ' . $firstResult;
 ```
 
+See also the [examples](examples/).
+
 This function will only return after ANY of the given `$promises` has been
 fulfilled or will throw when ALL of them have been rejected. In the meantime,
 the event loop will run any events attached to the same loop.
@@ -195,6 +199,8 @@ $allResults = Block\awaitAll($promises, $loop, $timeout);
 echo 'First promise resolved with: ' . $allResults[0];
 ```
 
+See also the [examples](examples/).
+
 This function will only return after ALL of the given `$promises` have been
 fulfilled or will throw when ANY of them have been rejected. In the meantime,
 the event loop will run any events attached to the same loop.

composer.json

@@ -23,6 +23,7 @@
         "react/promise-timer": "^1.5"
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8.35"
+        "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8.35",
+        "react/http": "^1.0"
     }
 }

examples/01-await.php

@@ -0,0 +1,36 @@
+<?php
+
+use Clue\React\Block;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * @param string $url
+ * @return Psr\Http\Message\ResponseInterface
+ * @throws Exception when HTTP request fails
+ */
+function requestHttp($url)
+{
+    // use a unique event loop instance for this operation
+    $loop = React\EventLoop\Factory::create();
+
+    // This example uses an HTTP client
+    $browser = new React\Http\Browser($loop);
+
+    // set up one request
+    $promise = $browser->get($url);
+
+    try {
+        // keep the loop running (i.e. block) until the response arrives
+        $result = Block\await($promise, $loop);
+
+        // promise successfully fulfilled with $result
+        return $result;
+    } catch (Exception $exception) {
+        // promise rejected with $exception
+        throw $exception;
+    }
+}
+
+$response = requestHttp('http://www.google.com/');
+echo $response->getBody();

examples/02-await-any.php

@@ -0,0 +1,40 @@
+<?php
+
+use Clue\React\Block;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * @param string $url1
+ * @param string $url2
+ * @return Psr\Http\Message\ResponseInterface
+ * @throws Exception when HTTP request fails
+ */
+function requestHttpFastestOfMultiple($url1, $url2)
+{
+    // use a unique event loop instance for all parallel operations
+    $loop = React\EventLoop\Factory::create();
+
+    // This example uses an HTTP client
+    $browser = new React\Http\Browser($loop);
+
+    // set up two parallel requests
+    $promises = array(
+        $browser->get($url1),
+        $browser->get($url2)
+    );
+
+    try {
+        // keep the loop running (i.e. block) until the first response arrives
+        $fasterResponse = Block\awaitAny($promises, $loop);
+
+        // promise successfully fulfilled with $fasterResponse
+        return $fasterResponse;
+    } catch (Exception $exception) {
+        // promise rejected with $exception
+        throw $exception;
+    }
+}
+
+$first = requestHttpFastestOfMultiple('http://www.google.com/', 'http://www.google.co.uk/');
+echo $first->getBody();

examples/03-await-all.php

@@ -0,0 +1,41 @@
+<?php
+
+use Clue\React\Block;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * @param string $url1
+ * @param string $url2
+ * @return Psr\Http\Message\ResponseInterface[]
+ * @throws Exception when HTTP request fails
+ */
+function requestHttpMultiple($url1, $url2)
+{
+    // use a unique event loop instance for all parallel operations
+    $loop = React\EventLoop\Factory::create();
+
+    // This example uses an HTTP client
+    $browser = new React\Http\Browser($loop);
+
+    // set up two parallel requests
+    $promises = array(
+        $browser->get($url1),
+        $browser->get($url2)
+    );
+
+    try {
+        // keep the loop running (i.e. block) until all responses arrive
+        $allResults = Block\awaitAll($promises, $loop);
+
+        // promise successfully fulfilled with $allResults
+        return $allResults;
+    } catch (Exception $exception) {
+        // promise rejected with $exception
+        throw $exception;
+    }
+}
+
+$all = requestHttpMultiple('http://www.google.com/', 'http://www.google.co.uk/');
+echo 'First promise resolved with: ' . $all[0]->getBody() . PHP_EOL;
+echo 'Second promise resolved with: ' . $all[1]->getBody() . PHP_EOL;

src/functions.php

@@ -66,6 +66,8 @@ function sleep($time, LoopInterface $loop)
  * }
  * ```
  *
+ * See also the [examples](../examples/).
+ *
  * If no `$timeout` argument is given and the promise stays pending, then this
  * will potentially wait/block forever until the promise is settled.
  *
@@ -143,6 +145,8 @@ function ($error) use (&$exception, &$rejected, &$wait, $loop) {
  * echo 'First result: ' . $firstResult;
  * ```
  *
+ * See also the [examples](../examples/).
+ *
  * This function will only return after ANY of the given `$promises` has been
  * fulfilled or will throw when ALL of them have been rejected. In the meantime,
  * the event loop will run any events attached to the same loop.
@@ -221,6 +225,8 @@ function awaitAny(array $promises, LoopInterface $loop, $timeout = null)
  * echo 'First promise resolved with: ' . $allResults[0];
  * ```
  *
+ * See also the [examples](../examples/).
+ *
  * This function will only return after ALL of the given `$promises` have been
  * fulfilled or will throw when ANY of them have been rejected. In the meantime,
  * the event loop will run any events attached to the same loop.