1: <?php
  2: 
  3: namespace React\Socket;
  4: 
  5: use React\Stream\DuplexStreamInterface;
  6: 
  7: /**
  8:  * Any incoming and outgoing connection is represented by this interface,
  9:  * such as a normal TCP/IP connection.
 10:  *
 11:  * An incoming or outgoing connection is a duplex stream (both readable and
 12:  * writable) that implements React's
 13:  * [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface).
 14:  * It contains additional properties for the local and remote address (client IP)
 15:  * where this connection has been established to/from.
 16:  *
 17:  * Most commonly, instances implementing this `ConnectionInterface` are emitted
 18:  * by all classes implementing the [`ServerInterface`](#serverinterface) and
 19:  * used by all classes implementing the [`ConnectorInterface`](#connectorinterface).
 20:  *
 21:  * Because the `ConnectionInterface` implements the underlying
 22:  * [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface)
 23:  * you can use any of its events and methods as usual:
 24:  *
 25:  * ```php
 26:  * $connection->on('data', function ($chunk) {
 27:  *     echo $chunk;
 28:  * });
 29:  *
 30:  * $connection->on('end', function () {
 31:  *     echo 'ended';
 32:  * });
 33:  *
 34:  * $connection->on('error', function (Exception $e) {
 35:  *     echo 'error: ' . $e->getMessage();
 36:  * });
 37:  *
 38:  * $connection->on('close', function () {
 39:  *     echo 'closed';
 40:  * });
 41:  *
 42:  * $connection->write($data);
 43:  * $connection->end($data = null);
 44:  * $connection->close();
 45:  * // …
 46:  * ```
 47:  *
 48:  * For more details, see the
 49:  * [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface).
 50:  *
 51:  * @see DuplexStreamInterface
 52:  * @see ServerInterface
 53:  * @see ConnectorInterface
 54:  */
 55: interface ConnectionInterface extends DuplexStreamInterface
 56: {
 57:     /**
 58:      * Returns the remote address (client IP and port) where this connection has been established with
 59:      *
 60:      * ```php
 61:      * $address = $connection->getRemoteAddress();
 62:      * echo 'Connection with ' . $address . PHP_EOL;
 63:      * ```
 64:      *
 65:      * If the remote address can not be determined or is unknown at this time (such as
 66:      * after the connection has been closed), it MAY return a `NULL` value instead.
 67:      *
 68:      * Otherwise, it will return the full remote address as a string value.
 69:      * If this is a TCP/IP based connection and you only want the remote IP, you may
 70:      * use something like this:
 71:      *
 72:      * ```php
 73:      * $address = $connection->getRemoteAddress();
 74:      * $ip = trim(parse_url('tcp://' . $address, PHP_URL_HOST), '[]');
 75:      * echo 'Connection with ' . $ip . PHP_EOL;
 76:      * ```
 77:      *
 78:      * @return ?string remote address (client IP and port) or null if unknown
 79:      */
 80:     public function getRemoteAddress();
 81: 
 82:     /**
 83:      * Returns the full local address (client IP and port) where this connection has been established with
 84:      *
 85:      * ```php
 86:      * $address = $connection->getLocalAddress();
 87:      * echo 'Connection with ' . $address . PHP_EOL;
 88:      * ```
 89:      *
 90:      * If the local address can not be determined or is unknown at this time (such as
 91:      * after the connection has been closed), it MAY return a `NULL` value instead.
 92:      *
 93:      * Otherwise, it will return the full local address as a string value.
 94:      *
 95:      * This method complements the [`getRemoteAddress()`](#getremoteaddress) method,
 96:      * so they should not be confused.
 97:      *
 98:      * If your `Server` instance is listening on multiple interfaces (e.g. using
 99:      * the address `0.0.0.0`), you can use this method to find out which interface
100:      * actually accepted this connection (such as a public or local interface).
101:      *
102:      * If your system has multiple interfaces (e.g. a WAN and a LAN interface),
103:      * you can use this method to find out which interface was actually
104:      * used for this connection.
105:      *
106:      * @return ?string local address (client IP and port) or null if unknown
107:      * @see self::getRemoteAddress()
108:      */
109:     public function getLocalAddress();
110: }
111: