react-websocket/README.md

# ReactPHP WebSockets

This is a library that implements WebSocket support on top of ReactPHPs HttpServer. In the process, the underlaying request and endpoint info is made available to your code. What happens next is up to you.

## Missing Features

This library is under development, and should not be used in any projects yet. The API and implementation may change in the future, and some features are still not implemented, or work in progress:

* Timeouts -- Disconnect the client on ping/pong timeout, and optionally on inactivity/idle.
* Error Handling -- Protocol errors should close the connection etc.
* Exceptions -- Exceptions should be thrown when relevant errors are encountered, such as bad encoding or data.
* Fragmented Messages -- Sending and receiving messages fragmented over multiple frames need work.

## Installing

Install using composer:

```shell
$ composer require noccylabs/react-websocket:^0.1.0
```

Note that you may need additional permissions to be able to access the repository. If so, clone it locally:

```shell
$ git clone https://dev.noccylabs.info/noccy/react-websocket ~/react-websocket
$ composer config repositories.react-websocket vcs ~/react-websocket
$ composer require noccylabs/react-websocket:^0.1.0 # ^0.1.0 or @dev
```

## Server

The WebSocket handler is built as a HttpServer middleware. This makes sense as WebSocket as a protocol is running over HTTP. Connections are set up by the middleware and exposed via the `connect` event.

Data is written and read as with any DuplexStream, use the write() method to send data to the client, and listen for the text and binary events on the connection. 

Note that the write() method sends text frames, if you want to send a binary frame use writeBinary().

### Example

```php
// This is the middleware that will intercept WebSocket handshakes
$websocket = new NoccyLabs\React\WebSocket\WebSocketMiddleware();

// Connect event handler, receives a WebSocketInterface.
// Ratchet handles security for you, this library does not. You should
// check everything important in the connect handler and reject anything
// that does not smell right. Here we just echo everything.
$websocket->on('connection', function (NoccyLabs\React\WebSocket\WebSocketInterface $connection) {
    $websocket->on('text', function ($text) use ($websocket) {
        $websocket->write($text);
    });
});

// The HTTP router that will handle other requests
$router = function (Psr\Http\Message\ServerRequestInterface $request) {
    return React\Http\Message\Response::plaintext("This is a websocket server");
};

// Create a HttpServer and insert the middleware
$http = new React\Http\HttpServer(
    $websocket,
    $router
);

// Create a socket and listen as you're used to
$socket = new React\Socket\SocketServer('0.0.0.0:8000');
$http->listen($socket); 

```

### WebSocketMiddleware Events

#### connection

```php
function (WebSocketInterface $member)
```

This event is emitted when a new WebSocket request has been accepted. The `WebSocketConnection` is passed as the first argument.

### WebSocketConnection events

#### ping

```php
function (string $payload)
```

This event will be emitted upon receiving a frame with a ping opcode. The pong response has already been sent automatically, unless 'no_auto_pong' is set in the context.

#### pong

```php
function (string $payload)
```

This event will be emitted upon receiving a frame with a pong opcode.

#### text

```php
function (string $payload)
```

This event will be emitted when a text data frame have been received and decoded.

#### binary

```php
function (string $payload)
```

This event will be emitted when a binary data frame have been received and decoded.

#### close

```php
function ()
```

#### error

```php
function (?string $reason, ?int $code)
```

### GroupManager events

#### create

```php
function (ConnectionGroup $group)
```

#### destroy

```php
function (ConnectionGroup $group)
```

### ConnectionGroup events

#### join

```php
function (WebSocketInterface $member)
```

#### leave

```php
function (WebSocketInterface $member)
```