Restructure examples to ease getting started

Author: clue

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:
 

examples/01-echo.php examples/01-echo-server.phpexamples/01-echo.php renamed to 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;

examples/04-http-server.php examples/03-http-server.phpexamples/04-http-server.php renamed to examples/03-http-server.php

@@ -12,21 +12,21 @@
 //
 // Just start this server and send a request to it:
 //
-// $ php examples/04-http-server.php 8000
+// $ 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/04-http-server.php tls://127.0.0.1:8000 examples/localhost.pem
+// $ 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/04-http-server.php unix:///tmp/server.sock
+// $ php examples/03-http-server.php unix:///tmp/server.sock
 // $ nc -U /tmp/server.sock
 
 use React\EventLoop\Factory;

examples/11-http.php examples/11-http-client.phpexamples/11-http.php renamed to examples/11-http-client.php

@@ -3,28 +3,34 @@
 // 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
+// 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;
 
-$target = isset($argv[1]) ? $argv[1] : 'www.google.com:80';
+$host = isset($argv[1]) ? $argv[1] : 'www.google.com';
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 $connector = new Connector($loop);
 
-$connector->connect($target)->then(function (ConnectionInterface $connection) use ($target) {
+$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: $target\r\n\r\n");
+    $connection->write("GET / HTTP/1.0\r\nHost: $host\r\n\r\n");
 }, 'printf');
 
 $loop->run();

examples/12-https.php examples/12-https-client.phpexamples/12-https.php renamed to examples/12-https-client.php

@@ -4,27 +4,33 @@
 // 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;
 
-$target = isset($argv[1]) ? $argv[1] : 'www.google.com:443';
+$host = isset($argv[1]) ? $argv[1] : 'www.google.com';
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 $connector = new Connector($loop);
 
-$connector->connect('tls://' . $target)->then(function (ConnectionInterface $connection) use ($target) {
+$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: $target\r\n\r\n");
+    $connection->write("GET / HTTP/1.0\r\nHost: $host\r\n\r\n");
 }, 'printf');
 
 $loop->run();

examples/13-netcat.php examples/21-netcat-client.phpexamples/13-netcat.php renamed to examples/21-netcat-client.php

@@ -4,6 +4,9 @@
 // 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;

examples/14-web.php examples/22-http-client.phpexamples/14-web.php renamed to examples/22-http-client.php

@@ -4,7 +4,14 @@
 // 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
+// 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;

examples/03-benchmark.php examples/91-benchmark-server.phpexamples/03-benchmark.php renamed to 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