1<?php 2 3namespace React\Socket; 4 5use 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 */ 55interface ConnectionInterface extends DuplexStreamInterface 56{ 57 /** 58 * Returns the full remote address (URI) 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 address (URI) as a string value, such 69 * as `tcp://127.0.0.1:8080`, `tcp://[::1]:80`, `tls://127.0.0.1:443`, 70 * `unix://example.sock` or `unix:///path/to/example.sock`. 71 * Note that individual URI components are application specific and depend 72 * on the underlying transport protocol. 73 * 74 * If this is a TCP/IP based connection and you only want the remote IP, you may 75 * use something like this: 76 * 77 * ```php 78 * $address = $connection->getRemoteAddress(); 79 * $ip = trim(parse_url($address, PHP_URL_HOST), '[]'); 80 * echo 'Connection with ' . $ip . PHP_EOL; 81 * ``` 82 * 83 * @return ?string remote address (URI) or null if unknown 84 */ 85 public function getRemoteAddress(); 86 87 /** 88 * Returns the full local address (full URI with scheme, IP and port) where this connection has been established with 89 * 90 * ```php 91 * $address = $connection->getLocalAddress(); 92 * echo 'Connection with ' . $address . PHP_EOL; 93 * ``` 94 * 95 * If the local address can not be determined or is unknown at this time (such as 96 * after the connection has been closed), it MAY return a `NULL` value instead. 97 * 98 * Otherwise, it will return the full address (URI) as a string value, such 99 * as `tcp://127.0.0.1:8080`, `tcp://[::1]:80`, `tls://127.0.0.1:443`, 100 * `unix://example.sock` or `unix:///path/to/example.sock`. 101 * Note that individual URI components are application specific and depend 102 * on the underlying transport protocol. 103 * 104 * This method complements the [`getRemoteAddress()`](#getremoteaddress) method, 105 * so they should not be confused. 106 * 107 * If your `TcpServer` instance is listening on multiple interfaces (e.g. using 108 * the address `0.0.0.0`), you can use this method to find out which interface 109 * actually accepted this connection (such as a public or local interface). 110 * 111 * If your system has multiple interfaces (e.g. a WAN and a LAN interface), 112 * you can use this method to find out which interface was actually 113 * used for this connection. 114 * 115 * @return ?string local address (URI) or null if unknown 116 * @see self::getRemoteAddress() 117 */ 118 public function getLocalAddress(); 119} 120