Nexus API Reference

WebSocketContext
in

Runtime context for an active WebSocket connection.

A WebSocketContext is injected into a WebSocketHandler via the #[FromContext] constructor attribute. It provides everything needed to communicate with the connected client: send text or binary frames, issue a ping, close the connection, and inspect the original HTTP upgrade request. The context is scoped to a single connection and must not be shared across connections.

Example — echo handler using the context directly:

final class EchoHandler extends WebSocketHandler
{
    public function __construct(
        #[FromContext] private readonly WebSocketContext $ctx,
    ) }

    public function onMessage(WebSocketFrame $frame): void
    {
        if ($this->ctx->isAlive()) {
            $this->ctx->send($frame->data);
        }
    }

    public function onClose(int $code): void
    {
        // Connection is already closed here; do not call send().
    }
}
Tags
see
WebSocketHandler

Abstract base class that receives this context via injection

see
WebSocketFrame

Represents an incoming WebSocket frame passed to onMessage()

psalm-api

Table of Contents

Methods

close()  : void
Close the WebSocket connection with an optional status code and reason.
id()  : int
Returns the numeric connection identifier assigned by the server.
isAlive()  : bool
Returns true if the connection is still open and accepting frames.
request()  : ServerRequestInterface
Returns the original HTTP upgrade request that initiated the connection.
send()  : void
Send a UTF-8 text frame to the client.
sendBinary()  : void
Send a binary frame to the client.
sendPing()  : void
Send a WebSocket ping frame to check connection liveness.
withRequest()  : self
Return a copy of the context with a different underlying PSR-7 request.

Methods

close()

Close the WebSocket connection with an optional status code and reason.

public close([int $code = 1000 ][, string $reason = '' ]) : void
Parameters
$code : int = 1000

WebSocket close code (default 1000 = normal closure).

$reason : string = ''

Human-readable reason phrase sent to the client.

id()

Returns the numeric connection identifier assigned by the server.

public id() : int
Return values
int

isAlive()

Returns true if the connection is still open and accepting frames.

public isAlive() : bool
Return values
bool

request()

Returns the original HTTP upgrade request that initiated the connection.

public request() : ServerRequestInterface

Useful for reading headers, cookies, or query parameters set during the WebSocket handshake (e.g. authentication tokens or channel parameters).

Return values
ServerRequestInterface

send()

Send a UTF-8 text frame to the client.

public send(string $text) : void
Parameters
$text : string

The UTF-8 encoded payload to transmit.

sendBinary()

Send a binary frame to the client.

public sendBinary(string $data) : void
Parameters
$data : string

The raw binary payload to transmit.

sendPing()

Send a WebSocket ping frame to check connection liveness.

public sendPing() : void

The client should respond with a pong frame automatically.

withRequest()

Return a copy of the context with a different underlying PSR-7 request.

public withRequest(ServerRequestInterface $request) : self

The dispatcher uses this to attach FastRoute path-param attributes to the stored request BEFORE the actor sees the context — otherwise a channel actor could not look up $conn->request()->getAttribute('id') for a route like /ws/games/{id}.

Parameters
$request : ServerRequestInterface
Return values
self 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results