phrity/websocket PHP Library

The library uses a middleware pattern to intercept and process various stages of the WebSocket lifecycle. You can implement WebSocket\Middleware\MiddlewareInterface to hook into:

• HTTP Handshake: processHttpIncoming and processHttpOutgoing.
• WebSocket Messages: processIncoming and processOutgoing.
• Lifecycle Ticks: processTick (useful for periodic tasks like heartbeats).

Common built-in middlewares include:

• WebSocket\Middleware\CompressionExtension: For handling per-message compression.
• WebSocket\Middleware\PingInterval: To automatically send pings.
• WebSocket\Middleware\SubprotocolNegotiation: To handle WebSocket subprotocols.

The library categorizes exceptions into different levels that dictate how the application responds:

Middlewares extend the server's functionality during message exchange. The library provides two essential middlewares for standard WebSocket operability:

• WebSocket\Middleware\CloseHandler: Automatically handles incoming and outgoing Close requests.
• WebSocket\Middleware\PingResponder: Automatically responds to Ping messages with Pong messages.

If these are not added, you must manually implement the logic to handle connection closing and ping/pong heartbeats.

$server = new WebSocket\Server();
$server
    ->addMiddleware(new WebSocket\Middleware\CloseHandler())
    ->addMiddleware(new WebSocket\Middleware\PingResponder());

The way messages are received has changed significantly in 2.x:

Client

• The receive() method now always returns an instance of Message (such as Text, Binary, Ping, Pong, or Close). In 1.x, this was controlled by the return_obj option, but it is now the standard behavior.
• Recommended approach: Use listener callback methods instead of manual polling with receive().

Server

• The Server no longer has a receive() method.
• Required approach: You must use listener callback methods to handle incoming messages.

To extend the library with custom logic, you can implement your own middleware by implementing the relevant interfaces provided by the library. Custom middlewares can intercept and handle three main areas of operation:

1. WebSocket message transfers: Intercepting data sent or received.
2. HTTP handshake operations: Modifying or reacting to the initial connection upgrade.
3. Tick operability: Handling periodic internal library tasks.

The CompressionExtension middleware adds support for message compression to your WebSocket client or server. You enable compression by passing one or more compressor instances as arguments to the CompressionExtension constructor.

Negotiation Logic:

• Client: Requests compression methods in the order they were added to the middleware.
• Server: Responds with the first compression method it supports from the client's list.
• Fallback: If the client and server cannot agree on a method, messages will be sent without compression.

$client_or_server->addMiddleware(new WebSocket\Middleware\CompressionExtension(
    new WebSocket\Middleware\CompressionExtension\DeflateCompressor()
));

The PingInterval middleware provides heartbeat functionality by sending Ping messages at a specified interval. This is typically used to keep connections alive and prevent them from being closed due to inactivity.

Key Behaviors:

• If no interval is specified, the middleware defaults to using the connection's timeout configuration as the interval.
• Important: You should generally set the interval to a value lower than your core connection timeout configuration. If the runner is blocked for the duration of the timeout, the PingInterval might not execute until the connection has already been considered timed out.

To use it, add the middleware to your client or server instance using addMiddleware().

$client_or_server->addMiddleware(new WebSocket\Middleware\PingInterval(interval: 10));

The CloseHandler middleware implements the standard WebSocket protocol behavior for closing connections. You should add this middleware to your client or server instance unless you are providing a custom implementation of close handling.

It manages the following lifecycle events:

• Receiving a Close message: Automatically responds with a Close confirmation message.
• Receiving a Close confirmation message: Automatically closes the connection.
• Sending a Close message: Blocks any further messages from being sent on that connection to ensure protocol compliance.

$client_or_server->addMiddleware(new WebSocket\Middleware\CloseHandler());

Unit testing is performed using PHPUnit, and code coverage is measured using PCOV. All pull requests must pass all tests and maintain 100% code coverage.

# Run unit tests
make test

# Create coverage
make coverage