Mark TcpServer and SecureServer as advanced usage

Author: clue

README.md

@@ -31,10 +31,11 @@ handle multiple concurrent connections without blocking.
     * [resume()](#resume)
     * [close()](#close)
   * [Server](#server)
-  * [TcpServer](#tcpserver)
-  * [SecureServer](#secureserver)
-  * [LimitingServer](#limitingserver)
-    * [getConnections()](#getconnections)
+  * [Advanced server usage](#advanced-server-usage)
+    * [TcpServer](#tcpserver)
+    * [SecureServer](#secureserver)
+    * [LimitingServer](#limitingserver)
+      * [getConnections()](#getconnections)
 * [Client usage](#client-usage)
   * [ConnectorInterface](#connectorinterface)
     * [connect()](#connect)
@@ -55,8 +56,8 @@ Here is a server that closes the connection if you send it anything:
 
 ```php
 $loop = React\EventLoop\Factory::create();
+$socket = new React\Socket\Server('127.0.0.1:8080', $loop);
 
-$socket = new React\Socket\TcpServer(8080, $loop);
 $socket->on('connection', function (ConnectionInterface $conn) {
     $conn->write("Hello " . $conn->getRemoteAddress() . "!\n");
     $conn->write("Welcome to this amazing server!\n");
@@ -322,10 +323,9 @@ Calling this method more than once on the same instance is a NO-OP.
 
 ### Server
 
-The `Server` class implements the [`ServerInterface`](#serverinterface) and
-is responsible for accepting plaintext TCP/IP connections.
-It acts as a facade for the underlying [`TcpServer`](#tcpserver) and follows
-its exact semantics.
+The `Server` class is the main class in this package that implements the
+[`ServerInterface`](#serverinterface) and allows you to accept incoming
+streaming connections, such as plaintext TCP/IP or secure TLS connection streams.
 
 ```php
 $server = new Server(8080, $loop);
@@ -461,7 +461,9 @@ See also the [`ServerInterface`](#serverinterface) for more details.
   If you want to typehint in your higher-level protocol implementation, you SHOULD
   use the generic [`ServerInterface`](#serverinterface) instead.
 
-### TcpServer
+### Advanced server usage
+
+#### TcpServer
 
 The `TcpServer` class implements the [`ServerInterface`](#serverinterface) and
 is responsible for accepting plaintext TCP/IP connections.
@@ -550,7 +552,7 @@ $server->on('connection', function (ConnectionInterface $connection) {
 
 See also the [`ServerInterface`](#serverinterface) for more details.
 
-### SecureServer
+#### SecureServer
 
 The `SecureServer` class implements the [`ServerInterface`](#serverinterface)
 and is responsible for providing a secure TLS (formerly known as SSL) server.
@@ -630,7 +632,7 @@ If you use a custom `ServerInterface` and its `connection` event does not
 meet this requirement, the `SecureServer` will emit an `error` event and
 then close the underlying connection.
 
-### LimitingServer
+#### LimitingServer
 
 The `LimitingServer` decorator wraps a given `ServerInterface` and is responsible
 for limiting and keeping track of open connections to this server instance.
@@ -697,7 +699,7 @@ $server->on('connection', function (ConnectionInterface $connection) {
 });
 ```
 
-#### getConnections()
+##### getConnections()
 
 The `getConnections(): ConnectionInterface[]` method can be used to
 return an array with all currently active connections.

examples/01-echo.php

@@ -8,26 +8,22 @@
 //
 // You can also run a secure TLS echo server like this:
 //
-// $ php examples/01-echo.php 8000 examples/localhost.pem
+// $ php examples/01-echo.php tls://127.0.0.1:8000 examples/localhost.pem
 // $ openssl s_client -connect localhost:8000
 
 use React\EventLoop\Factory;
-use React\Socket\TcpServer;
+use React\Socket\Server;
 use React\Socket\ConnectionInterface;
-use React\Socket\SecureServer;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new TcpServer(isset($argv[1]) ? $argv[1] : 0, $loop);
-
-// secure TLS mode if certificate is given as second parameter
-if (isset($argv[2])) {
-    $server = new SecureServer($server, $loop, array(
-        'local_cert' => $argv[2]
-    ));
-}
+$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) {
     echo '[connected]' . PHP_EOL;

examples/02-chat-server.php

@@ -8,27 +8,23 @@
 //
 // You can also run a secure TLS chat server like this:
 //
-// $ php examples/02-chat-server.php 8000 examples/localhost.pem
+// $ php examples/02-chat-server.php tls://127.0.0.1:8000 examples/localhost.pem
 // $ openssl s_client -connect localhost:8000
 
 use React\EventLoop\Factory;
-use React\Socket\TcpServer;
+use React\Socket\Server;
 use React\Socket\ConnectionInterface;
-use React\Socket\SecureServer;
 use React\Socket\LimitingServer;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new TcpServer(isset($argv[1]) ? $argv[1] : 0, $loop);
-
-// secure TLS mode if certificate is given as second parameter
-if (isset($argv[2])) {
-    $server = new SecureServer($server, $loop, array(
-        'local_cert' => $argv[2]
-    ));
-}
+$server = new Server(isset($argv[1]) ? $argv[1] : 0, $loop, array(
+    'tls' => array(
+        'local_cert' => isset($argv[2]) ? $argv[2] : (__DIR__ . '/localhost.pem')
+    )
+));
 
 $server = new LimitingServer($server, null);
 

examples/03-benchmark.php

@@ -11,28 +11,24 @@
 //
 // You can also run a secure TLS benchmarking server like this:
 //
-// $ php examples/03-benchmark.php 8000 examples/localhost.pem
+// $ php examples/03-benchmark.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
 
 use React\EventLoop\Factory;
-use React\Socket\TcpServer;
+use React\Socket\Server;
 use React\Socket\ConnectionInterface;
-use React\Socket\SecureServer;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
-$server = new TcpServer(isset($argv[1]) ? $argv[1] : 0, $loop);
-
-// secure TLS mode if certificate is given as second parameter
-if (isset($argv[2])) {
-    $server = new SecureServer($server, $loop, array(
-        'local_cert' => $argv[2]
-    ));
-}
+$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) use ($loop) {
     echo '[connected]' . PHP_EOL;