Menu

Reference

Reference / Http\WebSocket

Options

finalclass
final class Options

Settings for a WebSocket connection, server or client side.

Every setting is a public property with a fluent setter of the same name that returns the same object, so options chain:

$o = (new Options())->protocols(['chat.v2'])->pingInterval(15.0)->compression(true);

Durations are in seconds. An Options is passed to upgrade() on the server and to connect() on the client; the same object may serve many connections.

See also: upgrade, connect

Properties

maxMessageSizeintLargest accepted message, in bytes, after reassembly and decompression.
maxFrameSizeintLargest accepted single frame payload, in bytes.
pingIntervalfloatSeconds of silence before a ping is sent; also the read timeout.
pongTimeoutfloatSeconds to wait for the answer to a keepalive ping before the connection is dropped (close code 1006).
closeTimeoutfloatSeconds to wait for the peer's Close frame after sending ours.
connectTimeoutfloatSeconds allowed for the TCP/TLS connect and the handshake response together, as one deadline (client only).
sslContextarray<string,mixed>TLS options for wss:// (client only), in the shape of a stream context's ssl options: verify_peer, cafile, and so on.
protocolsarray<int,string>Subprotocols, in order of preference.
allowedOriginsarray<int,string>Origins allowed to upgrade (server only).
compressionboolNegotiate permessage-deflate (RFC 7692) compression.
compressionMinBytesintWith compression on, only messages of at least this many bytes are compressed.

maxMessageSize#source

int $maxMessageSize = 16777216

Largest accepted message, in bytes, after reassembly and decompression. Default 16 MiB. A bigger message closes the connection with 1009.

maxFrameSize#source

int $maxFrameSize = 16777216

Largest accepted single frame payload, in bytes. Default 16 MiB. Checked from the frame header before the payload is read; a bigger frame closes the connection with 1009.

pingInterval#source

float $pingInterval = 30.0

Seconds of silence before a ping is sent; also the read timeout. Default 30. 0 turns keepalive off.

pongTimeout#source

float $pongTimeout = 10.0

Seconds to wait for the answer to a keepalive ping before the connection is dropped (close code 1006). Default 10.

closeTimeout#source

float $closeTimeout = 5.0

Seconds to wait for the peer's Close frame after sending ours. Default 5.

connectTimeout#source

float $connectTimeout = 10.0

Seconds allowed for the TCP/TLS connect and the handshake response together, as one deadline (client only). Default 10.

sslContext#source

array<string,mixed> $sslContext = []

TLS options for wss:// (client only), in the shape of a stream context's ssl options: verify_peer, cafile, and so on. Default empty. SNI and the peer name are filled in from the URL's host.

protocols#source

array<int,string> $protocols = []

Subprotocols, in order of preference. Default empty.

Server: the first entry of the client's Sec-WebSocket-Protocol list that is also in this array is chosen; with no match no protocol header is sent. Client: all entries are offered, and a protocol the server answers with must be one of them.

allowedOrigins#source

array<int,string> $allowedOrigins = []

Origins allowed to upgrade (server only). Default empty, which checks nothing. When non-empty, a request whose Origin header is not an exact member of this list (including a request with no Origin) gets a 403. Set it whenever the connection is privileged: a browser sends cookies on a cross-site WebSocket upgrade and CORS does not police it.

compression#source

bool $compression = false

Negotiate permessage-deflate (RFC 7692) compression. Default off; turn it on at both ends.

compressionMinBytes#source

int $compressionMinBytes = 256

With compression on, only messages of at least this many bytes are compressed. Default 256.

Methods

maxMessageSize()Set {@see $maxMessageSize}.
maxFrameSize()Set {@see $maxFrameSize}.
pingInterval()Set {@see $pingInterval}.
pongTimeout()Set {@see $pongTimeout}.
closeTimeout()Set {@see $closeTimeout}.
connectTimeout()Set {@see $connectTimeout}.
sslContext()Set {@see $sslContext}.
protocols()Set {@see $protocols}.
allowedOrigins()Set {@see $allowedOrigins}.
compression()Set {@see $compression}.
compressionMinBytes()Set {@see $compressionMinBytes}.

maxMessageSize()#source

function maxMessageSize(int $n): Options

Set {@see $maxMessageSize}. Also lowers {@see $maxFrameSize} when that is larger than the new limit.

Parameters

$n int
limit in bytes

Returns

Options — this object

maxFrameSize()#source

function maxFrameSize(int $n): Options

Set {@see $maxFrameSize}.

Parameters

$n int
limit in bytes

Returns

Options — this object

pingInterval()#source

function pingInterval(float $s): Options

Set {@see $pingInterval}.

Parameters

$s float
seconds; 0 turns keepalive off

Returns

Options — this object

pongTimeout()#source

function pongTimeout(float $s): Options

Set {@see $pongTimeout}.

Parameters

$s float
seconds

Returns

Options — this object

closeTimeout()#source

function closeTimeout(float $s): Options

Set {@see $closeTimeout}.

Parameters

$s float
seconds

Returns

Options — this object

connectTimeout()#source

function connectTimeout(float $s): Options

Set {@see $connectTimeout}.

Parameters

$s float
seconds

Returns

Options — this object

sslContext()#source

function sslContext(array<string,mixed> $ssl): Options

Set {@see $sslContext}.

Parameters

$ssl array<string,mixed>
ssl stream-context options

Returns

Options — this object

protocols()#source

function protocols(array<int,string> $p): Options

Set {@see $protocols}.

Parameters

$p array<int,string>
subprotocol names, most preferred first

Returns

Options — this object

allowedOrigins()#source

function allowedOrigins(array<int,string> $o): Options

Set {@see $allowedOrigins}.

Parameters

$o array<int,string>
allowed Origin values, for example https://example.com

Returns

Options — this object

compression()#source

function compression(bool $on): Options

Set {@see $compression}.

Parameters

$on bool
true to negotiate permessage-deflate

Returns

Options — this object

compressionMinBytes()#source

function compressionMinBytes(int $n): Options

Set {@see $compressionMinBytes}.

Parameters

$n int
threshold in bytes

Returns

Options — this object

View source