Merge pull request #35 from SimonFrings/readme

Update README to reactphp/http v1.0.0 and add improved HTTP examples

Author: clue

README.md

@@ -203,12 +203,29 @@ $connector->connect('tls://smtp.googlemail.com:465')->then(function (ConnectionI
 
 #### HTTP requests
 
-HTTP operates on a higher layer than this low-level HTTP CONNECT implementation.
-If you want to issue HTTP requests, you can add a dependency for
-[clue/reactphp-buzz](https://github.com/clue/reactphp-buzz).
-It can interact with this library by issuing all
-[HTTP requests through a HTTP CONNECT proxy server](https://github.com/clue/reactphp-buzz#http-proxy).
-This works for both plain HTTP and TLS-encrypted HTTPS requests.
+This library also allows you to send HTTP requests through an HTTP CONNECT proxy server.
+
+In order to send HTTP requests, you first have to add a dependency for [ReactPHP's async HTTP client](https://github.com/reactphp/http#client-usage). This allows you to send both plain HTTP and TLS-encrypted HTTPS requests like this:
+
+```php
+$proxy = new Clue\React\HttpProxy\ProxyConnector(
+    'http://127.0.0.1:8080',
+    new React\Socket\Connector($loop)
+);
+
+$connector = new React\Socket\Connector($loop, array(
+    'tcp' => $proxy,
+    '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());
+}); 
+```
+
+See also [ReactPHP's HTTP client](https://github.com/reactphp/http#client-usage) and any of the [examples](examples) for more details.
 
 #### Connection timeout
 

composer.json

@@ -25,6 +25,7 @@
     "require-dev": {
         "phpunit/phpunit": "^9.0 || ^7.0 || ^5.0 || ^4.8",
         "react/event-loop": "^1.0 || ^0.5 || ^0.4 || ^0.3",
+        "react/http": "^1.0",
         "clue/block-react": "^1.1"
     }
 }

examples/01-http-request.php

@@ -0,0 +1,38 @@
+<?php
+
+// A simple example which uses an HTTP client to request https://example.com/ through an HTTP CONNECT proxy.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy defaults to localhost:8080.
+// To run the example go to the project root and run:
+//
+// $ php examples/01-http-requests.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/01-http-requests.php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$url = getenv('http_proxy');
+if ($url === false) {
+    $url = 'localhost:8080';
+}
+
+$loop = React\EventLoop\Factory::create();
+$proxy = new Clue\React\HttpProxy\ProxyConnector($url, new React\Socket\Connector($loop));
+
+$connector = new React\Socket\Connector($loop, array(
+    'tcp' => $proxy,
+    '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());
+}, 'printf');
+
+$loop->run();

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

@@ -0,0 +1,38 @@
+<?php
+
+// A simple example which uses an HTTP client to request https://example.com/ (optional: Through an HTTP CONNECT proxy.)
+// To run the example, go to the project root and run:
+//
+// $ php examples/02-optional-proxy-http-request.php
+//
+// If you chose the optional route, you can use any kind of proxy, for example https://github.com/leproxy/leproxy 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:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/02-optional-proxy-http-request.php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = React\EventLoop\Factory::create();
+
+$connector = null;
+$url = getenv('http_proxy');
+if ($url !== false) {
+    $connector = new React\Socket\Connector($loop);
+    $proxy = new Clue\React\HttpProxy\ProxyConnector($url, $connector);
+    $connector = new React\Socket\Connector($loop, array(
+        'tcp' => $proxy,
+        '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());
+}, 'printf');
+
+$loop->run();

examples/01-proxy-https.php renamed to examples/11-proxy-raw-https-protocol.php

@@ -1,18 +1,32 @@
 <?php
 
 // A simple example which requests https://google.com/ through an HTTP CONNECT proxy.
-// The proxy can be given as first argument and defaults to localhost:8080 otherwise.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy defaults to localhost:8080.
+// To run the example, go to the project root and run:
+//
+// $ php examples/11-proxy-raw-https-protocol.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/11-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 https://github.com/clue/reactphp-buzz#http-proxy
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
 
 use Clue\React\HttpProxy\ProxyConnector;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$url = isset($argv[1]) ? $argv[1] : '127.0.0.1:8080';
+$url = getenv('http_proxy');
+if ($url === false) {
+    $url = 'localhost:8080';
+}
 
 $loop = React\EventLoop\Factory::create();
 

examples/02-optional-proxy-https.php renamed to examples/12-optional-proxy-raw-https-protocol.php

@@ -1,14 +1,24 @@
 <?php
 
-// A simple example which requests https://google.com/ either directly or through
-// an HTTP CONNECT proxy.
-// The Proxy can be given as first argument or does not use a proxy otherwise.
+// A simple example which requests https://google.com/ directly (optional: Through an HTTP CONNECT proxy.)
+// To run the example, go to the project root and run:
+//
+// $ php examples/12-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 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:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/12-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 https://github.com/clue/reactphp-buzz#http-proxy
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
 
 use Clue\React\HttpProxy\ProxyConnector;
 use React\Socket\Connector;
@@ -20,9 +30,9 @@
 
 $connector = new Connector($loop);
 
-// first argument given? use this as the proxy URL
-if (isset($argv[1])) {
-    $proxy = new ProxyConnector($argv[1], $connector);
+$url = getenv('http_proxy');
+if ($url !== false) {
+    $proxy = new ProxyConnector($url, $connector);
     $connector = new Connector($loop, array(
         'tcp' => $proxy,
         'timeout' => 3.0,

examples/03-custom-proxy-headers.php renamed to examples/13-custom-proxy-headers.php

@@ -1,18 +1,32 @@
 <?php
 
 // A simple example which requests https://google.com/ through an HTTP CONNECT proxy.
-// The proxy can be given as first argument and defaults to localhost:8080 otherwise.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy defaults to localhost:8080.
+// To run the example, go to the project root and run:
+//
+// $ php examples/13-custom-proxy-headers.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/13-custom-proxy-headers.php
 //
 // For illustration purposes only. If you want to send HTTP requests in a real
-// world project, take a look at https://github.com/clue/reactphp-buzz#http-proxy
+// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
 
 use Clue\React\HttpProxy\ProxyConnector;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$url = isset($argv[1]) ? $argv[1] : '127.0.0.1:8080';
+$url = getenv('http_proxy');
+if ($url === false) {
+    $url = 'localhost:8080';
+}
 
 $loop = React\EventLoop\Factory::create();
 

examples/11-proxy-smtp.php renamed to examples/21-proxy-raw-smtp-protocol.php

@@ -1,7 +1,19 @@
 <?php
 
-// A simple example which uses a plain SMTP connection to Googlemail through a HTTP CONNECT proxy.
-// Proxy can be given as first argument and defaults to localhost:8080 otherwise.
+// A simple example which requests https://google.com/ through an HTTP CONNECT proxy.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy defaults to localhost:8080.
+// To run the example, go to the project root and run:
+//
+// $ php examples/21-proxy-raw-smtp-protocol.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/21-proxy-raw-smtp-protocol.php
+//
 // Please note that MANY public proxies do not allow SMTP connections, YMMV.
 
 use Clue\React\HttpProxy\ProxyConnector;
@@ -10,7 +22,10 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$url = isset($argv[1]) ? $argv[1] : '127.0.0.1:8080';
+$url = getenv('http_proxy');
+if ($url === false) {
+    $url = 'localhost:8080';
+}
 
 $loop = React\EventLoop\Factory::create();
 

examples/12-proxy-smtps.php renamed to examples/22-proxy-raw-smtps-protocol.php

@@ -1,7 +1,19 @@
 <?php
 
-// A simple example which uses a secure SMTP connection to Googlemail through a HTTP CONNECT proxy.
-// Proxy can be given as first argument and defaults to localhost:8080 otherwise.
+// A simple example which requests https://google.com/ through an HTTP CONNECT proxy.
+// You can use any kind of proxy, for example https://github.com/leproxy/leproxy and execute it like this:
+//
+// $ php leproxy.php
+//
+// The proxy defaults to localhost:8080.
+// To run the example, go to the project root and run:
+//
+// $ php examples/22-proxy-raw-smtps-protocol.php
+//
+// To run the same example with your proxy, the proxy URL can be given as an environment variable:
+//
+// $ http_proxy=127.0.0.2:8080 php examples/22-proxy-raw-smtps-protocol.php
+//
 // This example highlights how changing from plain connections (see previous
 // example) to using a secure connection actually adds very little complexity
 // and does not mess with your actual network protocol otherwise.
@@ -13,7 +25,10 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$url = isset($argv[1]) ? $argv[1] : '127.0.0.1:8080';
+$url = getenv('http_proxy');
+if ($url === false) {
+    $url = 'localhost:8080';
+}
 
 $loop = React\EventLoop\Factory::create();