Restructure examples to ease getting started

.travis.yml

@@ -46,4 +46,4 @@ install:
 
 script:
   - vendor/bin/phpunit --coverage-text
-  - time php examples/benchmark-throughput.php
+  - time php examples/91-benchmark-throughput.php

examples/01-http.php

@@ -0,0 +1,40 @@
+<?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.
+//
+// $ php examples/01-http.php
+// $ php examples/01-http.php reactphp.org
+
+use React\EventLoop\Factory;
+use React\Stream\DuplexResourceStream;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$host = isset($argv[1]) ? $argv[1] : 'www.google.com';
+
+// connect to tcp://www.google.com:80 (blocking call!)
+// for illustration purposes only, should use react/http-client or react/socket instead!
+$resource = stream_socket_client('tcp://' . $host . ':80');
+if (!$resource) {
+    exit(1);
+}
+
+$loop = Factory::create();
+$stream = new DuplexResourceStream($resource, $loop);
+
+$stream->on('data', function ($chunk) {
+    echo $chunk;
+});
+$stream->on('close', function () {
+    echo '[CLOSED]' . PHP_EOL;
+});
+
+$stream->write("GET / HTTP/1.0\r\nHost: $host\r\n\r\n");
+
+$loop->run();

examples/02-https.php

@@ -0,0 +1,40 @@
+<?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.
+//
+// $ php examples/02-https.php
+// $ php examples/02-https.php reactphp.org
+
+use React\EventLoop\Factory;
+use React\Stream\DuplexResourceStream;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$host = isset($argv[1]) ? $argv[1] : 'www.google.com';
+
+// connect to tls://www.google.com:443 (blocking call!)
+// for illustration purposes only, should use react/http-client or react/socket instead!
+$resource = stream_socket_client('tls://' . $host . ':443');
+if (!$resource) {
+    exit(1);
+}
+
+$loop = Factory::create();
+$stream = new DuplexResourceStream($resource, $loop);
+
+$stream->on('data', function ($chunk) {
+    echo $chunk;
+});
+$stream->on('close', function () {
+    echo '[CLOSED]' . PHP_EOL;
+});
+
+$stream->write("GET / HTTP/1.0\r\nHost: $host\r\n\r\n");
+
+$loop->run();

examples/11-cat.php

@@ -0,0 +1,28 @@
+<?php
+
+// Simple example piping everything from STDIN to STDOUT.
+// This allows you to output everything you type on your keyboard or to redirect
+// the pipes to show contents of files and other streams.
+//
+// $ php examples/11-cat.php
+// $ php examples/11-cat.php < README.md
+// $ echo hello | php examples/11-cat.php
+
+use React\EventLoop\Factory;
+use React\Stream\ReadableResourceStream;
+use React\Stream\WritableResourceStream;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+if (DIRECTORY_SEPARATOR === '\\') {
+    fwrite(STDERR, 'Non-blocking console I/O not supported on Microsoft Windows' . PHP_EOL);
+    exit(1);
+}
+
+$loop = Factory::create();
+
+$stdout = new WritableResourceStream(STDOUT, $loop);
+$stdin = new ReadableResourceStream(STDIN, $loop);
+$stdin->pipe($stdout);
+
+$loop->run();

examples/benchmark-throughput.php → examples/91-benchmark-throughput.php

@@ -1,7 +1,23 @@
 <?php
 
+// Benchmark to measure throughput performance piping an input stream to an output stream.
+// This allows you to get an idea of how fast stream processing with PHP can be
+// and also to play around with differnt types of input and output streams.
+//
+// This example accepts a number of parameters to control the timeout (-t 1),
+// the input file (-i /dev/zero) and the output file (-o /dev/null).
+//
+// $ php examples/91-benchmark-throughput.php
+// $ php examples/91-benchmark-throughput.php -t 10 -o zero.bin
+// $ php examples/91-benchmark-throughput.php -t 60 -i zero.bin
+
 require __DIR__ . '/../vendor/autoload.php';
 
+if (DIRECTORY_SEPARATOR === '\\') {
+    fwrite(STDERR, 'Non-blocking console I/O not supported on Microsoft Windows' . PHP_EOL);
+    exit(1);
+}
+
 $args = getopt('i:o:t:');
 $if = isset($args['i']) ? $args['i'] : '/dev/zero';
 $of = isset($args['o']) ? $args['o'] : '/dev/null';