Add improved HTTP examples and adapt documentation

composer.json

@@ -24,6 +24,7 @@
     "require-dev": {
         "phpunit/phpunit": "^9.0 || ^7.0 || ^6.0 || ^5.7 || ^4.8.35",
         "react/event-loop": "^1.0 || ^0.5 || ^0.4 || ^0.3",
+        "react/http": "^1.0",
         "clue/connection-manager-extra": "^1.0 || ^0.7",
         "clue/block-react": "^1.1"
     }

examples/01-https-request.php

@@ -0,0 +1,41 @@
+<?php
+
+// A simple example which uses an HTTP client to request https://example.com/ through a SOCKS proxy.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy (defaults to localhost:8080) and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy in this example defaults to localhost:1080.
+// To run the example go to the project root and run:
+//
+// $ php examples/01-https-request.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ socks_proxy=127.0.0.2:1080 php examples/01-https-request.php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$url = getenv('socks_proxy');
+if ($url === false) {
+    $url = 'localhost:1080';
+}
+
+$loop = React\EventLoop\Factory::create();
+$client = new Clue\React\Socks\Client($url, new React\Socket\Connector($loop));
+
+$connector = new React\Socket\Connector($loop, array(
+    'tcp' => $client,
+    'timeout' => 3.0,
+    'dns' => false
+));
+
+$browser = new React\Http\Browser($loop, $connector);
+
+$browser->get('https://example.com/')->then(function (Psr\Http\Message\ResponseInterface $response) {
+    var_dump($response->getHeaders(), (string) $response->getBody());
+}, function (Exception $error) {
+    var_dump('There was an error', $error->getMessage());
+});
+
+$loop->run();

examples/02-optional-proxy-https-request.php

@@ -0,0 +1,40 @@
+<?php
+
+// A simple example which uses an HTTP client to request https://example.com/ (optional: Through a SOCKS proxy.)
+// To run the example, go to the project root and run:
+//
+// $ php examples/02-optional-proxy-https-request.php
+//
+// If you chose the optional route, you can use any kind of proxy, for example https://github.com/leproxy/leproxy (defaults to localhost:8080) and execute it like this:
+//
+// $ php leproxy.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ socks_proxy=127.0.0.2:1080 php examples/02-optional-proxy-https-request.php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = React\EventLoop\Factory::create();
+
+$connector = null;
+$url = getenv('socks_proxy');
+if ($url !== false) {
+    $connector = new React\Socket\Connector($loop);
+    $client = new Clue\React\Socks\Client($url, $connector);
+    $connector = new React\Socket\Connector($loop, array(
+        'tcp' => $client,
+        'timeout' => 3.0,
+        'dns' => false
+    ));
+}
+
+$browser = new React\Http\Browser($loop, $connector);
+
+$browser->get('https://example.com/')->then(function (Psr\Http\Message\ResponseInterface $response) {
+    var_dump($response->getHeaders(), (string) $response->getBody());
+}, function (Exception $error) {
+    var_dump('There was an error', $error->getMessage());
+});
+
+$loop->run();

examples/11-proxy-raw-http-protocol.php

@@ -0,0 +1,48 @@
+<?php
+
+// A simple example which requests http://google.com/ through a SOCKS proxy.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy (defaults to localhost:8080) and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy in this example defaults to localhost:1080.
+// To run the example, go to the project root and run:
+//
+// $ php examples/11-proxy-raw-http-protocol.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ socks_proxy=127.0.0.2:1080 php examples/11-proxy-raw-http-protocol.php
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$url = getenv('socks_proxy');
+if ($url === false) {
+    $url = 'localhost:1080';
+}
+
+$loop = React\EventLoop\Factory::create();
+
+$client = new Clue\React\Socks\Client($url, new React\Socket\Connector($loop));
+$connector = new React\Socket\Connector($loop, array(
+    'tcp' => $client,
+    'timeout' => 3.0,
+    'dns' => false
+));
+
+echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
+
+$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $stream) {
+    echo 'connected' . PHP_EOL;
+    $stream->write("GET / HTTP/1.0\r\n\r\n");
+    $stream->on('data', function ($data) {
+        echo $data;
+    });
+}, function (Exception $error) {
+    var_dump('There was an error', $error->getMessage());
+});
+
+$loop->run();

examples/12-optional-proxy-raw-http-protocol.php

@@ -0,0 +1,51 @@
+<?php
+
+// A simple example which requests http://google.com/ directly (optional: Through a SOCKS proxy.)
+// To run the example, go to the project root and run:
+//
+// $ php examples/12-optional-proxy-raw-http-protocol.php
+//
+// If you chose the optional route, you can use any kind of proxy, for example https://github.com/leproxy/leproxy (defaults to localhost:8080) and execute it like this:
+//
+// $ php leproxy.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ socks_proxy=127.0.0.2:1080 php examples/12-optional-proxy-raw-http-protocol.php
+//
+// This example highlights how changing from direct connection to using a proxy
+// actually adds very little complexity and does not mess with your actual
+// network protocol otherwise.
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = React\EventLoop\Factory::create();
+
+$connector = new React\Socket\Connector($loop);
+
+$url = getenv('socks_proxy');
+if ($url !== false) {
+    $client = new Clue\React\Socks\Client($url, $connector);
+    $connector = new React\Socket\Connector($loop, array(
+        'tcp' => $client,
+        'timeout' => 3.0,
+        'dns' => false
+    ));
+}
+
+echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
+
+$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $stream) {
+    echo 'connected' . PHP_EOL;
+    $stream->write("GET / HTTP/1.0\r\n\r\n");
+    $stream->on('data', function ($data) {
+        echo $data;
+    });
+}, function (Exception $error) {
+    var_dump('There was an error', $error->getMessage());
+});
+
+$loop->run();

examples/13-proxy-raw-https-protocol.php

@@ -0,0 +1,48 @@
+<?php
+
+// A simple example which requests http://google.com/ through a SOCKS proxy.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy (defaults to localhost:8080) and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy in this example defaults to localhost:1080.
+// To run the example, go to the project root and run:
+//
+// $ php examples/13-proxy-raw-https-protocol.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ socks_proxy=127.0.0.2:1080 php examples/13-proxy-raw-https-protocol.php
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$url = getenv('socks_proxy');
+if ($url === false) {
+    $url = 'localhost:1080';
+}
+
+$loop = React\EventLoop\Factory::create();
+
+$client = new Clue\React\Socks\Client($url, new React\Socket\Connector($loop));
+$connector = new React\Socket\Connector($loop, array(
+    'tcp' => $client,
+    'timeout' => 3.0,
+    'dns' => false
+));
+
+echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
+
+$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $stream) {
+    echo 'connected' . PHP_EOL;
+    $stream->write("GET / HTTP/1.0\r\n\r\n");
+    $stream->on('data', function ($data) {
+        echo $data;
+    });
+}, function (Exception $error) {
+    var_dump('There was an error', $error->getMessage());
+});
+
+$loop->run();

examples/14-optional-proxy-raw-https-protocol.php

@@ -0,0 +1,51 @@
+<?php
+
+// A simple example which requests http://google.com/ directly (optional: Through a SOCKS proxy.)
+// To run the example, go to the project root and run:
+//
+// $ php examples/14-optional-proxy-raw-https-protocol.php
+//
+// If you chose the optional route, you can use any kind of proxy, for example https://github.com/leproxy/leproxy (defaults to localhost:8080) and execute it like this:
+//
+// $ php leproxy.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ socks_proxy=127.0.0.2:1080 php examples/14-optional-proxy-raw-https-protocol.php
+//
+// This example highlights how changing from direct connection to using a proxy
+// actually adds very little complexity and does not mess with your actual
+// network protocol otherwise.
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = React\EventLoop\Factory::create();
+
+$connector = new React\Socket\Connector($loop);
+
+$url = getenv('socks_proxy');
+if ($url !== false) {
+    $client = new Clue\React\Socks\Client($url, $connector);
+    $connector = new React\Socket\Connector($loop, array(
+        'tcp' => $client,
+        'timeout' => 3.0,
+        'dns' => false
+    ));
+}
+
+echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
+
+$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $stream) {
+    echo 'connected' . PHP_EOL;
+    $stream->write("GET / HTTP/1.0\r\n\r\n");
+    $stream->on('data', function ($data) {
+        echo $data;
+    });
+}, function (Exception $error) {
+    var_dump('There was an error', $error->getMessage());
+});
+
+$loop->run();