Websocket

MMO\core\server · 1 symbol · generated 30 Sep 2026

class

Websocket

A hand-rolled RFC 6455 WebSocket server: a single instance listens for one TCP connection (listen), performs the HTTP-Upgrade handshake, then exchanges framed messages over it (readMessage/write).

class MMO\core\server\Websocket implements Psr\Http\Message\StreamInterface, MMO\core\interfaces\iRenderable

Namespace: MMO\core\server
Implements: StreamInterface, iRenderable

$ws = new Websocket('localhost', 49666, false); $ws->connect(); $ws->listen(); // blocks until one client connects and completes the handshake $msg = $ws->readMessage(); // blocks until a full message arrives $ws->write("you said: $msg"); $ws->close();

Index

	MODE_BINARY
	MODE_RAW
	MODE_TEXT
	OP_BINARY
	OP_CLOSE
	OP_CONTINUATION
	OP_PING
	OP_PONG
	OP_TEXT
	WEBSOCKET_KEY	The magic GUID RFC 6455 requires appending to the client's Sec-WebSocket-Key before hashing it into the handshake's Sec-WebSocket-Accept.
	address
	closing
	port
	secure
	socket
	stream
	timeout
	close($message, $status)	StreamInterface::close Send a close frame (`OP_CLOSE`) and wait for the peer's acknowledgment, then release the client stream (`$stream`) -- always, whether the handshake actually completed o…
	connect()	Open the listening server socket (`$socket`) -- does NOT accept a connection yet (`listen` for that).
	debugName()
	detach()	StreamInterface::detach NOTE: unlike `close`, does not fclose the resource -- the caller takes ownership and must close it themselves.
	disconnect()	Close the client connection (`close`) and the listening server socket (`connect`).
	eof()	StreamInterface::eof
	getContents()	StreamInterface::getContents NOTE: reads raw, unframed bytes from the underlying socket -- not a WebSocket message (`readMessage` for that).
	getMetadata($key)	StreamInterface::getMetadata
	getResource()
	getSize()	StreamInterface::getSize
	getTimeout()
	getType()
	getUri()
	hasMessage()	Test if stream has awaiting command before calling stream->read.
	isConnected()
	isListening()
	isReadable()	StreamInterface::isReadable
	isSeekable()	StreamInterface::isSeekable
	isWritable()	StreamInterface::isWritable
	listen()	Wait for one client to connect (up to `setTimeout`, or indefinitely) and complete the WebSocket handshake (parses the HTTP Upgrade request's headers, verifies Sec-WebSocket-Key, and replies with…
	ping($message)	Send a ping frame (`OP_PING`); the peer is expected to reply with a pong.
	read($length)	StreamInterface::read NOTE: reads raw, unframed bytes from the underlying socket -- not a WebSocket frame/message (`readFrame`/
	readFrame()	Read and parse one raw WebSocket frame (RFC 6455 section 5.2) from the stream, unmasking its payload if masked.
	readLine($length, $ending)	Read line from stream.
	readMessage($code)	Read one full WebSocket message, transparently reassembling continuation frames (`OP_CONTINUATION`) and auto-handling control frames along the way: a ping (`OP_PING`) gets an automatic pong r…
	render($opts)	Get content of socket
	rewind()	StreamInterface::rewind
	run()	Run the websocket main loop.
	seek($offset, $whence)	StreamInterface::seek
	setTimeout($timeout)	Set timeout.
	Setup($url, $mainFile, $xdebugPort) static	Setup the websocket for a html exchange.
	tell()	StreamInterface::tell
	Url($address, $port, $secure) static	Generate a valid Javascript url for the websocket
	write($data, $mode)	StreamInterface::write A non-string $data is JSON-encoded first (`jsonEncode`).
	writeFrame($code, $payload, $final, $masked)	Write one raw WebSocket frame (RFC 6455 section 5.2): header (opcode/final bit/payload length) plus the (optionally masked) payload.
	writeMessage($code, $content, $masked, $framesize)	Write a full WebSocket message, splitting it into multiple frames (`writeFrame`) if it exceeds $framesize.
	__construct($address, $port, $secure)	constructor
	__destruct()	Destructor. Closes the stream
	__toString()	StreamInterface::__toString

Constants10

MODE_BINARY

const MODE_BINARY = 2

See: write's $mode: frame $data as a binary message (OP_BINARY).

MODE_RAW

const MODE_RAW = 0

See: write's $mode: write raw bytes with no WebSocket framing (used internally for the handshake and frame bytes themselves).

MODE_TEXT

const MODE_TEXT = 1

See: write's $mode: frame $data as a text message (OP_TEXT).

OP_BINARY

const OP_BINARY = 2

See: readFrame/writeFrame opcode: a binary message.

OP_CLOSE

const OP_CLOSE = 8

See: readFrame/writeFrame opcode: connection close (close/readMessage's auto-handling).

OP_CONTINUATION

const OP_CONTINUATION = 0

See: readFrame/writeFrame opcode: a continuation of a fragmented message (writeMessage's multi-frame splitting).

OP_PING

const OP_PING = 9

See: readFrame/writeFrame opcode: ping (ping) -- readMessage auto-replies with a pong.

OP_PONG

const OP_PONG = 10

See: readFrame/writeFrame opcode: pong, sent automatically by readMessage in reply to a ping.

OP_TEXT

const OP_TEXT = 1

See: readFrame/writeFrame opcode: a UTF-8 text message.

WEBSOCKET_KEY

The magic GUID RFC 6455 requires appending to the client's Sec-WebSocket-Key before hashing it into the handshake's Sec-WebSocket-Accept.

const WEBSOCKET_KEY = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'

Properties7

address

protected $address = null

closing

protected bool $closing = false

Type: bool

port

protected $port = null

secure

protected $secure = null

socket

protected $socket = null

stream

protected $stream = null

timeout

protected $timeout = null

Methods39

close($message, $status)

Websocket.php:366

StreamInterface::close Send a close frame (OP_CLOSE) and wait for the peer's acknowledgment, then release the client stream ($stream) -- always, whether the handshake actually completed or the peer was already gone (any failure along the way is logged, not thrown -- disconnect/__destruct rely on this never throwing).

function close(string $message = '', int $status = 1000): void

$message = ''	string	a human-readable close reason, sent to the peer.
$status = 1000	int	a WebSocket close status code (e.g. 1000 = normal closure, 1001 = going away).
returns	void

connect()

Websocket.php:230

Open the listening server socket ($socket) -- does NOT accept a connection yet (listen for that).

function connect(): void

returns	void
throws		if already connected, or the socket couldn't be created (e.g. the port is already in use).

debugName()

Websocket.php:187

function debugName(): string

returns

string

e.g. 'socket:localhost:49666'.

detach()

Websocket.php:408

StreamInterface::detach NOTE: unlike close, does not fclose the resource -- the caller takes ownership and must close it themselves.

function detach(): mixed

returns

mixed

the client stream (now detached from this Websocket), or null if none was connected.

disconnect()

Websocket.php:314

Close the client connection (close) and the listening server socket (connect).

function disconnect(): void

returns

void

eof()

Websocket.php:455

StreamInterface::eof

function eof(): bool

returns

bool

true if no client is connected, or the client stream has reached EOF.

getContents()

Websocket.php:479

StreamInterface::getContents NOTE: reads raw, unframed bytes from the underlying socket -- not a WebSocket message (readMessage for that).

function getContents(): string

returns	string
throws		if no client is connected, or reading fails.

getMetadata($key)

Websocket.php:346

StreamInterface::getMetadata

function getMetadata(?string $key = null): mixed

$key = null	null \| string
returns	mixed
throws		if no client is connected (`listen`).

getResource()

Websocket.php:194

function getResource()

returns the accepted client stream (listen), or null before a client has connected.

getSize()

Websocket.php:420

StreamInterface::getSize

function getSize(): ?int

returns

null | int

null if no client is connected, or the size can't be determined.

getTimeout()

Websocket.php:222

function getTimeout(): ?float

returns null | float the current accept timeout (setTimeout).

getType()

Websocket.php:354

function getType(): ?string

returns null | string the client stream's resource type (e.g. 'stream'), or null if no client is connected (isListening).

getUri()

Websocket.php:199

function getUri(): string

returns

string

'address:port'.

hasMessage()

Websocket.php:302

Test if stream has awaiting command before calling stream->read.

function hasMessage(): bool

NOTE: use this when inside a long command. As stream->read is blocking, call this before reading a command.

returns

bool

isConnected()

Websocket.php:309

function isConnected(): bool

returns bool whether the listening server socket is open (connect); NOT whether a client is connected (isListening for that).

isListening()

Websocket.php:292

function isListening(): bool

returns bool whether a client is currently connected (getType).

isReadable()

Websocket.php:431

StreamInterface::isReadable

function isReadable(): bool

returns

bool

always true.

isSeekable()

Websocket.php:447

StreamInterface::isSeekable

function isSeekable(): bool

returns

bool

always false -- a socket cannot be seeked.

isWritable()

Websocket.php:439

StreamInterface::isWritable

function isWritable(): bool

returns

bool

always true.

listen()

Websocket.php:246

Wait for one client to connect (up to setTimeout, or indefinitely) and complete the WebSocket handshake (parses the HTTP Upgrade request's headers, verifies Sec-WebSocket-Key, and replies with 101 Switching Protocols).

function listen(): void

returns	void
throws		if `connect` wasn't called first, or the handshake's headers are invalid.

ping($message)

Websocket.php:593

Send a ping frame (OP_PING); the peer is expected to reply with a pong. @return int bytes written.

function ping(string $message = ''): int

$message = ''	string
returns	int

read($length)

Websocket.php:535

StreamInterface::read NOTE: reads raw, unframed bytes from the underlying socket -- not a WebSocket frame/message (readFrame/

function read(int $length): string

See: readMessage for that). Any read failure (timeout, empty read, short read) closes the connection (close, with an appropriate WebSocket status code) before throwing.

$length	int	exact number of bytes to read.
returns	string	exactly $length bytes.
throws		if $length is negative.
throws		if the read times out (`setTimeout`).
throws		if no client is connected, the peer closed the connection, or fewer than $length bytes were read.

readFrame()

Websocket.php:739

Read and parse one raw WebSocket frame (RFC 6455 section 5.2) from the stream, unmasking its payload if masked.

protected function readFrame(): array

returns

array

[opcode, payload, final, masked].

readLine($length, $ending)

Websocket.php:513

Read line from stream.

function readLine(int $length, string $ending = ''): string

$length	int	Maximum number of bytes to read
$ending = ''	string	Line delimiter
returns	string	Read data

readMessage($code)

Websocket.php:633

Read one full WebSocket message, transparently reassembling continuation frames (OP_CONTINUATION) and auto-handling control frames along the way: a ping (OP_PING) gets an automatic pong reply, and a close frame (OP_CLOSE) is acknowledged (unless this side already initiated the close -- $closing) and ends the connection (closes and nulls $stream directly, without going through close).

function readMessage(?int &$code = null): string

$code = null	null \| int
returns	string	the reassembled message payload.
throws		propagated from `read`/`readFrame` on a connection failure.

render($opts)

Websocket.php:208

Get content of socket

function render(array $opts = []): string

$opts = []	array
returns	string

rewind()

Websocket.php:494

StreamInterface::rewind

function rewind(): void

returns	void
throws		always -- a socket cannot be seeked.

run()

Websocket.php:170

Run the websocket main loop. It yields the command that it receives.

function run(): Generator

A read timeout ([`setTimeout`](https://mmoframework.fr/documentation/mmo.core/php/server/Websocket.md#websocket-settimeout)) just skips to the next iteration rather than ending the loop; any other error is logged ([`Log::FromException`](https://mmoframework.fr/documentation/mmo.core/php/events/Log.md#log-fromexception)) and also doesn't end the loop -- only [`isListening`](https://mmoframework.fr/documentation/mmo.core/php/server/Websocket.md#websocket-islistening) turning false (e.g. after the client disconnects) does. WARNING: only use this function with a call to Websocket::Setup()

returns

Generator

seek($offset, $whence)

Websocket.php:502

StreamInterface::seek

function seek($offset, $whence = SEEK_SET): void

$offset
$whence = SEEK_SET
returns	void
throws		always -- a socket cannot be seeked.

setTimeout($timeout)

Websocket.php:216

Set timeout.

function setTimeout(?float $timeout): void

$timeout	null \| float	Timeout in seconds to wait for a client connection (`listen`); null waits indefinitely.
returns	void

Setup($url, $mainFile, $xdebugPort)

staticWebsocket.php:128

Setup the websocket for a html exchange.

static function Setup(string $url, string|int $mainFile = 1, string|bool $xdebugPort = false): ?self

It returns a websocket on the command line. If not on the command line, it will execute the mainFile script and returns null. WARNING: the mainFile MUST be able to be executed as standalone. It cannot be a file executed by `index.php` or an `.htaccess` redirection.

$url	string
$mainFile = 1	string \| int	the main file to execute when not on command line. if an int, it will look back at the $mainFile trace to find which file need to be executed on the command line
$xdebugPort = false	string \| bool	if true or a port, will start the script with xdebug (default port for xdebug is 9003)
returns	null \| self

```php $url = \MMO\core\server\Websocket::Url(); if ($websocket = \MMO\core\server\Websocket::Setup($url)) { //the following code is only executed on the command line foreach ($websocket->run() as $cmd) { ... } } //the following code is only executed by apache <script> let socket = "<? $url ?>"; socket.send('hello'); </script> ```

tell()

Websocket.php:463

StreamInterface::tell

function tell(): int

returns	int
throws		if no client is connected, or the position can't be determined.

Url($address, $port, $secure)

staticWebsocket.php:92

Generate a valid Javascript url for the websocket

static function Url(string $address = 'localhost', int $port = 49666, bool $secure = false): string

$address = 'localhost'	string	the host (ex: localhost)
$port = 49666	int	the port
$secure = false	bool	if the connection is secured
returns	string

write($data, $mode)

Websocket.php:571

StreamInterface::write A non-string $data is JSON-encoded first (jsonEncode).

function write(JsonSerializable|array|string $data, int $mode = self::MODE_TEXT): int

$data	JsonSerializable \| array \| string
$mode = self::MODE_TEXT	int	`MODE_TEXT`/`MODE_BINARY` (framed as a WebSocket message) or `MODE_RAW` (raw bytes, no framing).
returns	int	the number of bytes written.
throws		if no client is connected, or the raw write fails/is incomplete (`MODE_RAW`).
throws		if $mode isn't one of the MODE_* constants.

writeFrame($code, $payload, $final, $masked)

Websocket.php:697

Write one raw WebSocket frame (RFC 6455 section 5.2): header (opcode/final bit/payload length) plus the (optionally masked) payload.

protected function writeFrame(int $code, string $payload, bool $final = false, bool $masked = true): int

$code	int	the opcode (`OP_CONTINUATION`/`OP_TEXT`/...).
$payload	string	this frame's chunk of the message.
$final = false	bool	whether this is the last frame of the message.
$masked = true	bool	whether to XOR-mask the payload with a random 4-byte key (as RFC 6455 requires from a client).
returns	int	bytes written (verified against a real RFC-6455 frame parser, including the 16-bit extended-length form -- `writeMessage`'s default 4096-byte $framesize keeps individual frames under the 64-bit form's 65535-byte threshold, so that path is exercised only with a $framesize above it).

writeMessage($code, $content, $masked, $framesize)

Websocket.php:609

Write a full WebSocket message, splitting it into multiple frames (writeFrame) if it exceeds $framesize.

function writeMessage(int $code, string $content, bool $masked = true, int $framesize = 4096): int

$code	int	an opcode (`OP_TEXT`/`OP_BINARY`/`OP_CLOSE`/`OP_PING`/`OP_PONG`).
$content	string	the message payload.
$masked = true	bool	whether to mask the frame(s) (per RFC 6455, a server should send unmasked frames to a client, but this class defaults to `true` regardless of which side it's acting as -- masking a server frame is harmless to a spec-compliant client, which unmasks either way).
$framesize = 4096	int	maximum payload bytes per frame; larger content is split across continuation frames (`OP_CONTINUATION`).
returns	int	total bytes written across all frames (verified end-to-end with a 10000-byte message split across multiple frames).

__construct($address, $port, $secure)

Websocket.php:71

constructor

function __construct(string $address, int $port = 49666, bool $secure = true)

$address	string	can be the direct host (ex: localhost) or an entire url of the form `ws://localhost:4445`
$port = 49666	int	make sure you use port between 49152-65534 for your connection
$secure = true	bool	if true, use tls

__destruct()

Websocket.php:330

Destructor. Closes the stream

function __destruct()

__toString()

Websocket.php:337

StreamInterface::__toString

function __toString(): string

returns

string