Documentation for ConnectionInterface

reactphp · clue · Dec 19, 2016 · Nov 10, 2016 · Nov 11, 2016 · Nov 13, 2016
commit 993cf51283cea26908e6b25961e19335d0cd7f58
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ and [`Stream`](https://github.com/reactphp/stream) components.
 * [Quickstart example](#quickstart-example)
 * [Usage](#usage)
   * [Server](#server)
-  * [Connection](#connection)
+  * [ConnectionInterface](#connectioninterface)
 * [Install](#install)
 * [License](#license)
 
@@ -66,18 +66,55 @@ $loop->run();
 
 ### Server
 
-The server can listen on a port and will emit a `connection` event whenever a
-client connects.
+The `Server` class is responsible for listening on a port and waiting for new connections.
 
-### Connection
+Whenever a client connects, it will emit a `connection` event with a connection
+instance implementing [`ConnectionInterface`](#connectioninterface):
 
-The `Connection` is a duplex (readable and writable) [`Stream`](https://github.com/reactphp/stream).
-The incoming connection represents the server-side end of the connection.
+```php
+$server->on('connection', function (ConnectionInterface $connection) {
+    …
+});
+```
+
+### ConnectionInterface
 
+The `ConnectionInterface` is used to represent any incoming connection.
+
+An incoming connection is a duplex stream (both readable and writable) that
+implements React's
+[`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface)
+and contains only a single additional property, the remote address (client IP)
+where this connection has been established from.
+
+> Note that this interface is only to be used to represent the server-side end
+of an incoming connection.
 It MUST NOT be used to represent an outgoing connection in a client-side context.
 If you want to establish an outgoing connection,
 use the [`SocketClient`](https://github.com/reactphp/socket-client) component instead.
 
+Because the `ConnectionInterface` implements the underlying
+[`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface)
+you can use any of its events and methods as usual:
+
+```php
+$connection->on('data', function ($chunk) {
+    echo $data;
+});
+
+$conenction->on('close', function () {
+    echo 'closed';
+});
+
+$connection->write($data);
+$connection->end($data = null);
+$connection->close();
+// …
+```
+
+For more details, see the
+[`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface).
+
 ## Install
 
 The recommended way to install this library is [through Composer](http://getcomposer.org).

diff --git a/src/Connection.php b/src/Connection.php
@@ -4,6 +4,11 @@
 
 use React\Stream\Stream;
 
+/**
+ * The actual connection implementation for ConnectionInterface
+ *
+ * @see ConnectionInterface
+ */
 class Connection extends Stream implements ConnectionInterface
 {
     public function handleData($stream)

diff --git a/src/ConnectionInterface.php b/src/ConnectionInterface.php
@@ -4,6 +4,26 @@
 
 use React\Stream\DuplexStreamInterface;
 
+/**
+ * Any incoming connection is represented by this interface.
+ *
+ * An incoming connection is a duplex stream (both readable and writable) that
+ * implements React's DuplexStreamInterface and contains only a single
+ * additional property, the remote address (client IP) where this connection has
+ * been established from.
+ *
+ * Note that this interface is only to be used to represent the server-side end
+ * of an incoming connection.
+ * It MUST NOT be used to represent an outgoing connection in a client-side
+ * context.
+ * If you want to establish an outgoing connection,
+ * use React's SocketClient component instead.
+ *
+ * Because the `ConnectionInterface` implements the underlying
+ * `DuplexStreamInterface` you can use any of its events and methods as usual.
+ *
+ * @see DuplexStreamInterface
+ */
 interface ConnectionInterface extends DuplexStreamInterface
 {
     public function getRemoteAddress();