Merge pull request #136 from clue-labs/examples

jsor · web-flow · commit a73caf8622ba · 2017-11-18T17:15:49.000+01:00
Restructure examples to ease getting started
diff --git a/README.md b/README.md
@@ -1065,7 +1065,7 @@ $tcpConnector->connect('127.0.0.1:80')->then(function (ConnectionInterface $conn
 $loop->run();
 ```
 
-See also the [first example](examples).
+See also the [examples](examples).
 
 Pending connection attempts can be cancelled by cancelling its pending promise like so:
 
@@ -1133,7 +1133,7 @@ $dnsConnector->connect('www.google.com:80')->then(function (ConnectionInterface
 $loop->run();
 ```
 
-See also the [first example](examples).
+See also the [examples](examples).
 
 Pending connection attempts can be cancelled by cancelling its pending promise like so:
 
@@ -1178,7 +1178,7 @@ $secureConnector->connect('www.google.com:443')->then(function (ConnectionInterf
 $loop->run();
 ```
 
-See also the [second example](examples).
+See also the [examples](examples).
 
 Pending connection attempts can be cancelled by cancelling its pending promise like so:
 
diff --git a/examples/01-echo-server.php b/examples/01-echo-server.php
@@ -3,17 +3,17 @@
 // Just start this server and connect to it. Everything you send to it will be
 // sent back to you.
 //
-// $ php examples/01-echo.php 8000
+// $ php examples/01-echo-server.php 8000
 // $ telnet localhost 8000
 //
 // You can also run a secure TLS echo server like this:
 //
-// $ php examples/01-echo.php tls://127.0.0.1:8000 examples/localhost.pem
+// $ php examples/01-echo-server.php tls://127.0.0.1:8000 examples/localhost.pem
 // $ openssl s_client -connect localhost:8000
 //
 // You can also run a Unix domain socket (UDS) server like this:
 //
-// $ php examples/01-echo.php unix:///tmp/server.sock
+// $ php examples/01-echo-server.php unix:///tmp/server.sock
 // $ nc -U /tmp/server.sock
 
 use React\EventLoop\Factory;
diff --git a/examples/03-http-server.php b/examples/03-http-server.php
@@ -0,0 +1,57 @@
+<?php
+
+// Simple HTTP server example (for illustration purposes only).
+// This shows how a plaintext TCP/IP connection is accepted to then receive an
+// application level protocol message (HTTP request) and reply with an
+// application level protocol message (HTTP response) in return.
+//
+// This example exists for illustraion purposes only. It does not actually
+// parse incoming HTTP requests, so you can actually send *anything* and will
+// still respond with a valid HTTP response.
+// Real applications should use react/http instead!
+//
+// Just start this server and send a request to it:
+//
+// $ php examples/03-http-server.php 8000
+// $ curl -v http://localhost:8000/
+// $ ab -n1000 -c10 http://localhost:8000/
+// $ docker run -it --rm --net=host jordi/ab ab -n1000 -c10 http://localhost:8000/
+//
+// You can also run a secure HTTPS echo server like this:
+//
+// $ php examples/03-http-server.php tls://127.0.0.1:8000 examples/localhost.pem
+// $ curl -v --insecure https://localhost:8000/
+// $ ab -n1000 -c10 https://localhost:8000/
+// $ docker run -it --rm --net=host jordi/ab ab -n1000 -c10 https://localhost:8000/
+//
+// You can also run a Unix domain socket (UDS) server like this:
+//
+// $ php examples/03-http-server.php unix:///tmp/server.sock
+// $ nc -U /tmp/server.sock
+
+use React\EventLoop\Factory;
+use React\Socket\Server;
+use React\Socket\ConnectionInterface;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$server = new Server(isset($argv[1]) ? $argv[1] : 0, $loop, array(
+    'tls' => array(
+        'local_cert' => isset($argv[2]) ? $argv[2] : (__DIR__ . '/localhost.pem')
+    )
+));
+
+$server->on('connection', function (ConnectionInterface $conn) {
+    $conn->once('data', function () use ($conn) {
+        $body = "<html><h1>Hello world!</h1></html>\r\n";
+        $conn->end("HTTP/1.1 200 OK\r\nContent-Length: " . strlen($body) . "\r\nConnection: close\r\n\r\n" . $body);
+    });
+});
+
+$server->on('error', 'printf');
+
+echo 'Listening on ' . strtr($server->getAddress(), array('tcp:' => 'http:', 'tls:' => 'https:')) . PHP_EOL;
+
+$loop->run();
diff --git a/examples/11-http-client.php b/examples/11-http-client.php
@@ -0,0 +1,36 @@
+<?php
+
+// Simple plaintext HTTP client example (for illustration purposes only).
+// This shows how a plaintext TCP/IP connection is established to then send an
+// application level protocol message (HTTP).
+// Real applications should use react/http-client instead!
+//
+// This simple example only accepts an optional host parameter to send the
+// request to. See also example #22 for proper URI parsing.
+//
+// $ php examples/11-http-client.php
+// $ php examples/11-http-client.php reactphp.org
+
+use React\EventLoop\Factory;
+use React\Socket\Connector;
+use React\Socket\ConnectionInterface;
+
+$host = isset($argv[1]) ? $argv[1] : 'www.google.com';
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+$connector = new Connector($loop);
+
+$connector->connect($host. ':80')->then(function (ConnectionInterface $connection) use ($host) {
+    $connection->on('data', function ($data) {
+        echo $data;
+    });
+    $connection->on('close', function () {
+        echo '[CLOSED]' . PHP_EOL;
+    });
+
+    $connection->write("GET / HTTP/1.0\r\nHost: $host\r\n\r\n");
+}, 'printf');
+
+$loop->run();
diff --git a/examples/11-http.php b/examples/11-http.php
diff --git a/examples/12-https-client.php b/examples/12-https-client.php
@@ -0,0 +1,36 @@
+<?php
+
+// Simple secure HTTPS client example (for illustration purposes only).
+// This shows how a secure TLS connection is established to then send an
+// application level protocol message (HTTP).
+// Real applications should use react/http-client instead
+//
+// This simple example only accepts an optional host parameter to send the
+// request to. See also example #22 for proper URI parsing.
+//
+// $ php examples/12-https-client.php
+// $ php examples/12-https-client.php reactphp.org
+
+use React\EventLoop\Factory;
+use React\Socket\Connector;
+use React\Socket\ConnectionInterface;
+
+$host = isset($argv[1]) ? $argv[1] : 'www.google.com';
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+$connector = new Connector($loop);
+
+$connector->connect('tls://' . $host . ':443')->then(function (ConnectionInterface $connection) use ($host) {
+    $connection->on('data', function ($data) {
+        echo $data;
+    });
+    $connection->on('close', function () {
+        echo '[CLOSED]' . PHP_EOL;
+    });
+
+    $connection->write("GET / HTTP/1.0\r\nHost: $host\r\n\r\n");
+}, 'printf');
+
+$loop->run();
diff --git a/examples/12-https.php b/examples/12-https.php
diff --git a/examples/21-netcat-client.php b/examples/21-netcat-client.php
@@ -1,5 +1,13 @@
 <?php
 
+// Simple plaintext TCP/IP and secure TLS client example that pipes console I/O.
+// This shows how a plaintext TCP/IP or secure TLS connection is established and
+// then everything you type on STDIN will be sent and everything the server
+// sends will be piped to your STDOUT.
+//
+// $ php examples/21-netcat-client.php www.google.com:80
+// $ php examples/21-netcat-client.php tls://www.google.com:443
+
 use React\EventLoop\Factory;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;
@@ -8,6 +16,16 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
+if (!defined('STDIN')) {
+    echo 'STDIO streams require CLI SAPI' . PHP_EOL;
+    exit(1);
+}
+
+if (DIRECTORY_SEPARATOR === '\\') {
+    fwrite(STDERR, 'Non-blocking console I/O not supported on Microsoft Windows' . PHP_EOL);
+    exit(1);
+}
+
 if (!isset($argv[1])) {
     fwrite(STDERR, 'Usage error: required argument <host:port>' . PHP_EOL);
     exit(1);
diff --git a/examples/22-http-client.php b/examples/22-http-client.php
@@ -1,5 +1,18 @@
 <?php
 
+// Simple plaintext HTTP and secure HTTPS client example (for illustration purposes only).
+// This shows how an URI parameter can parsed to decide whether to establish
+// a plaintext TCP/IP or secure TLS connection and then send an
+// application level protocol message (HTTP).
+// Real applications should use react/http-client instead!
+//
+// Unlike examples #11 and #12, this example will actually take an optional URI
+// parameter and parse it to connect to the correct default port and use the
+// correct transport protocol.
+//
+// $ php examples/22-http-client.php
+// $ php examples/22-http-client.php https://reactphp.org/
+
 use React\EventLoop\Factory;
 use React\Socket\ConnectionInterface;
 use React\Socket\Connector;
diff --git a/examples/91-benchmark-server.php b/examples/91-benchmark-server.php
@@ -4,21 +4,21 @@
 // sent for each connection and will print the average throughput once the
 // connection closes.
 //
-// $ php examples/03-benchmark.php 8000
+// $ php examples/91-benchmark-server.php 8000
 // $ telnet localhost 8000
 // $ echo hello world | nc -N localhost 8000
 // $ dd if=/dev/zero bs=1M count=1000 | nc -N localhost 8000
 //
 // You can also run a secure TLS benchmarking server like this:
 //
-// $ php examples/03-benchmark.php tls://127.0.0.1:8000 examples/localhost.pem
+// $ php examples/91-benchmark-server.php tls://127.0.0.1:8000 examples/localhost.pem
 // $ openssl s_client -connect localhost:8000
 // $ echo hello world | openssl s_client -connect localhost:8000
 // $ dd if=/dev/zero bs=1M count=1000 | openssl s_client -connect localhost:8000
 //
 // You can also run a Unix domain socket (UDS) server benchmark like this:
 //
-// $ php examples/03-benchmark.php unix:///tmp/server.sock
+// $ php examples/91-benchmark-server.php unix:///tmp/server.sock
 // $ nc -N -U /tmp/server.sock
 // $ dd if=/dev/zero bs=1M count=1000 | nc -N -U /tmp/server.sock
 
