Amp WebSocket Client

https://github.com/amphp/websocket-client
Admin
Provides an asynchronous WebSocket client for PHP, enabling real-time communication and...
Tokens:49,742
Snippets:351
Trust Score:9.8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/amphp/websocket-client/blob/2.x/README.md

Install the package as a Composer dependency.

```bash
composer require amphp/websocket-client
```

--------------------------------

### Rfc6455Connector instantiation example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Example of creating a connector with a custom connection factory, shared HTTP client, and compression disabled. The HTTP client is built with default settings; compression is turned off by passing null.

```php
use Amp\Http\Client\HttpClientBuilder;
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\Client\Rfc6455Connector;

$httpClient = (new HttpClientBuilder)->build(); // shared transport

$connector = new Rfc6455Connector(
    connectionFactory: new Rfc6455ConnectionFactory(closePeriod: 1.0),
    httpClient: $httpClient,
    compressionContextFactory: null, // no permessage-deflate
);
```

--------------------------------

### Full custom configuration example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455ConnectionFactory.md

Example from the README showing how to instantiate Rfc6455ConnectionFactory with custom heartbeat, rate limit, parser factory, frame split threshold, and close period. Uses PeriodicHeartbeatQueue, ConstantRateLimit, and Rfc6455ParserFactory.

```php
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\ConstantRateLimit;
use Amp\Websocket\Parser\Rfc6455ParserFactory;
use Amp\Websocket\PeriodicHeartbeatQueue;

$connectionFactory = new Rfc6455ConnectionFactory(
    heartbeatQueue: new PeriodicHeartbeatQueue(
        heartbeatPeriod: 5, // 5 seconds
    ),
    rateLimit: new ConstantRateLimit(
        bytesPerSecondLimit: 2 ** 17, // 128 KiB
        framesPerSecondLimit: 10,
    ),
    parserFactory: new Rfc6455ParserFactory(
        messageSizeLimit: 2 ** 20, // 1 MiB
    ),
    frameSplitThreshold: 2 ** 14, // 16 KiB
    closePeriod: 0.5, // 0.5 seconds
);
```

--------------------------------

### WebsocketHandshake constructor usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Example of creating a WebsocketHandshake with a wss URI and an Origin header. The URI must use ws or wss scheme; otherwise a ValueError is thrown.

```php
use Amp\Websocket\Client\WebsocketHandshake;

$handshake = new WebsocketHandshake(
    'wss://example.com/websocket?token=abc',
    ['Origin' => 'https://example.com'],
);
```

--------------------------------

### Example — configuring a connector

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connector.md

Shows how to instantiate Rfc6455Connector with a custom connection factory and compression disabled.

```php
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\Client\Rfc6455Connector;

$connector = new Rfc6455Connector(
    connectionFactory: new Rfc6455ConnectionFactory(closePeriod: 1.0),
    compressionContextFactory: null, // disable permessage-deflate compression
);
```

--------------------------------

### Rfc6455ConnectionFactory configuration example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Example of configuring Rfc6455ConnectionFactory with heartbeat queue (5s), rate limit (128 KiB/s, 10 frames/s), parser factory (1 MiB message limit), frame split threshold (16 KiB), and close period (0.5s).

```php
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\ConstantRateLimit;
use Amp\Websocket\Parser\Rfc6455ParserFactory;
use Amp\Websocket\PeriodicHeartbeatQueue;

$connectionFactory = new Rfc6455ConnectionFactory(
    heartbeatQueue: new PeriodicHeartbeatQueue(heartbeatPeriod: 5),
    rateLimit: new ConstantRateLimit(
        bytesPerSecondLimit: 2 ** 17, // 128 KiB
        framesPerSecondLimit: 10,
    ),
    parserFactory: new Rfc6455ParserFactory(messageSizeLimit: 2 ** 20), // 1 MiB messages
    frameSplitThreshold: 2 ** 14, // 16 KiB
    closePeriod: 0.5,
);
```

--------------------------------

### receive() Usage Example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Loops over incoming messages and prints each one after buffering.

```php
while ($message = $connection->receive()) {
    printf("Got: %s\n", $message->buffer());
}
```

--------------------------------

### onClose method signature and usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Registers a callback/closure to run on connection close (per the underlying Rfc6455Client). The example prints a message when the connection closes.

```php
public function onClose(\Closure $onClose): void
```

```php
$connection->onClose(static function (): void {
    printf("Connection closed\n");
});
```

--------------------------------

### Full handshake configuration example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Shows configuring all immutable options via with*() methods, each returning a clone. Sets TCP/TLS timeouts, header size limit, adds a header, and manipulates query parameters.

```php
use Amp\Websocket\Client\WebsocketHandshake;

$handshake = (new WebsocketHandshake(
    'wss://example.com/socket?room=lobby',
    ['Origin' => 'https://example.com'],
))
    ->withTcpConnectTimeout(3.0)
    ->withTlsHandshakeTimeout(8.0)
    ->withHeaderSizeLimit(64 * 1024)
    ->withAddedHeader('Sec-WebSocket-Protocol', 'dumb-increment-protocol')
    ->withQueryParameter('room', 'lobby')
    ->withoutQueryParameter('debug');
```

--------------------------------

### Full realistic example with connect

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Configures a WebsocketHandshake with timeouts, header size limit, custom headers, and a query parameter, then attempts to connect. Catches ValueError for misconfiguration.

```php
use Amp\Websocket\Client\WebsocketHandshake;
use function Amp\Websocket\Client\connect;

$handshake = (new WebsocketHandshake('wss://api.example.com/live'))
    ->withTcpConnectTimeout(3.0)
    ->withTlsHandshakeTimeout(8.0)
    ->withHeaderSizeLimit(64 * 1024)
    ->withHeader('Origin', 'https://www.example.com')
    ->withHeader('Sec-WebSocket-Protocol', 'dumb-increment-protocol')
    ->withQueryParameter('apiKey', 'secret');

try {
    $connection = connect($handshake);
} catch (\ValueError $exception) {
    // Bad URI or non-ws/wss scheme.
    printf("Handshake misconfiguration: %s\n", $exception->getMessage());
}
```

--------------------------------

### withHeaderSizeLimit usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Sets the header size limit to 16 KiB.

```php
$handshake = (new WebsocketHandshake('ws://example.com/socket'))->withHeaderSizeLimit(16 * 1024);
```

--------------------------------

### ping() Usage Example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Sends a ping frame.

```php
$connection->ping();
```

--------------------------------

### Header configuration usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Shows chaining withHeader, withAddedHeader, and withoutHeader on a WebsocketHandshake instance to configure headers for a WebSocket connection.

```php
$handshake = (new WebsocketHandshake('ws://example.com/socket'))
    ->withHeader('Origin', 'http://localhost:1337')
    ->withAddedHeader('Sec-WebSocket-Protocol', 'chat, superchat')
    ->withoutHeader('Origin');
```

--------------------------------

### getIterator method signature and usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Returns a traversable that yields every WebsocketMessage until the connection closes, powering foreach ($connection as $message). The example iterates messages, buffers each payload, and closes the connection when the payload equals '100'.

```php
public function getIterator(): Traversable
```

```php
foreach ($connection as $message) {
    $payload = $message->buffer();
    if ($payload === '100') {
        $connection->close();
        break;
    }
}
```

--------------------------------

### Custom WebsocketConnectionFactory example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455ConnectionFactory.md

Shows a custom factory that decorates the default behavior by logging the socket addresses before delegating to the inner factory. Useful when implementing a custom WebsocketConnectionFactory.

```php
use Amp\Http\Client\Response;
use Amp\Socket\Socket;
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\Client\WebsocketConnection;
use Amp\Websocket\Client\WebsocketConnectionFactory;
use Amp\Websocket\Compression\WebsocketCompressionContext;

final class LoggingConnectionFactory implements WebsocketConnectionFactory
{
    private readonly Rfc6455ConnectionFactory $inner = new Rfc6455ConnectionFactory();

    public function createConnection(
        Response $handshakeResponse,
        Socket $socket,
        ?WebsocketCompressionContext $compressionContext = null,
    ): WebsocketConnection {
        printf(
            "Upgraded socket %s -> %s\n",
            $socket->getLocalAddress()->toString(),
            $socket->getRemoteAddress()->toString(),
        );

        return $this->inner->createConnection($handshakeResponse, $socket, $compressionContext);
    }
}
```

--------------------------------

### withUri usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Replaces the URI with a new one, e.g., switching from ws:// to wss://.

```php
$handshake = (new WebsocketHandshake('ws://a.example.com/socket'))->withUri('wss://b.example.com/socket');
```

--------------------------------

### close method signature and usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Initiates the WebSocket closing handshake. After the configured closePeriod, the socket is closed. The $code parameter defaults to WebsocketCloseCode::NORMAL_CLOSE and $reason defaults to an empty string. The example closes with GOING_AWAY and a reason.

```php
public function close(int $code = WebsocketCloseCode::NORMAL_CLOSE, string $reason = ''): void
```

```php
$connection->close(WebsocketCloseCode::GOING_AWAY, 'Client shutting down');
```

--------------------------------

### sendText() Usage Example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Sends a simple text message.

```php
$connection->sendText('Hello, world!');
```

--------------------------------

### streamText() Usage Example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Streams the contents of a file as a text message.

```php
use Amp\ByteStream\FileInputStream;

$connection->streamText(FileInputStream::open('/tmp/payload.txt'));
```

--------------------------------

### sendBinary() Usage Example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Sends a binary payload of repeated bytes.

```php
$connection->sendBinary(\str_repeat("\x00\xff", 1024));
```

--------------------------------

### Full realistic example using Rfc6455Connector

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Shows a complete connection lifecycle: connect to a WebSocket endpoint, send a text message, receive and process messages until a 'Goodbye!' payload triggers a close, and handle a WebsocketClosedException if the peer closes the connection. Uses the Rfc6455Connector class and the connect() function from Amp\Websocket\Client.

```php
use Amp\Websocket\Client\Rfc6455Connector;
use Amp\Websocket\Client\WebsocketHandshake;
use Amp\Websocket\WebsocketClosedException;
use function Amp\Websocket\Client\connect;

$connector = new Rfc6455Connector();
$connection = $connector->connect(new WebsocketHandshake('ws://localhost:1337/broadcast'));

try {
    $connection->sendText('Hello!');

    while ($message = $connection->receive()) {
        $payload = $message->buffer();
        printf("Received: %s\n", $payload);

        if ($payload === 'Goodbye!') {
            $connection->close();
            break;
        }
    }
} catch (WebsocketClosedException $exception) {
    printf("Closed by peer: %s\n", $exception->getReason());
}
```

--------------------------------

### getHandshakeResponse() Usage Example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Shows how to retrieve the handshake response and print the HTTP status code.

```php
$response = $connection->getHandshakeResponse();
printf("Upgraded with status %d\n", $response->getStatus());
```

--------------------------------

### Query parameter manipulation example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Shows how to modify query parameters on a WebsocketHandshake instance using withQueryParameter, withAddedQueryParameter, and withoutQueryParameter.

```php
$handshake = (new WebsocketHandshake('ws://example.com/socket?room=1&token=x'))
    ->withQueryParameter('room', '2')
    ->withAddedQueryParameter('token', 'y')
    ->withoutQueryParameter('debug');
```

--------------------------------

### WebsocketHandshake::withHeader()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/errors.md

Sets a single header. Throws \Error if the header name is empty or starts with a colon.

```APIDOC
## [METHOD] WebsocketHandshake::withHeader()

### Description
Sets a single header. Throws \Error if the header name is empty or starts with a colon.

### Method
withHeader

### Endpoint
`withHeader(string $name, string $value): WebsocketHandshake`

### Parameters
#### Method Parameters
- **$name** (string) - Required - Header name. Must not be empty or start with a colon.
- **$value** (string) - Required - Header value.

### Request Example
```php
$handshake = (new WebsocketHandshake('ws://example.com/'))->withHeader('X-Foo', 'bar');
```

### Response
#### Success Response
- Returns a new `WebsocketHandshake` instance with the updated header.

#### Error Response
- **\Error** - If the header name is empty or starts with a colon. Message: `Header name cannot be empty or start with a colon (:)`.

### Error Handling
Catch `\Error` to handle invalid header names.
```

--------------------------------

### withTlsHandshakeTimeout usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Sets the TLS handshake timeout to 15 seconds.

```php
$handshake = (new WebsocketHandshake('wss://example.com/socket'))->withTlsHandshakeTimeout(15.0);
```

--------------------------------

### WebsocketHandshake::withAddedHeader()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/errors.md

Adds a header to the existing set. Throws \Error if the header name is empty or starts with a colon.

```APIDOC
## [METHOD] WebsocketHandshake::withAddedHeader()

### Description
Adds a header to the existing set. Throws \Error if the header name is empty or starts with a colon.

### Method
withAddedHeader

### Endpoint
`withAddedHeader(string $name, string $value): WebsocketHandshake`

### Parameters
#### Method Parameters
- **$name** (string) - Required - Header name. Must not be empty or start with a colon.
- **$value** (string) - Required - Header value.

### Request Example
```php
$handshake = (new WebsocketHandshake('ws://example.com/'))->withAddedHeader('X-Foo', 'bar');
```

### Response
#### Success Response
- Returns a new `WebsocketHandshake` instance with the added header.

#### Error Response
- **\Error** - If the header name is empty or starts with a colon. Message: `Header name cannot be empty or start with a colon (:)`.

### Error Handling
Catch `\Error` to handle invalid header names.
```

--------------------------------

### Catch WebsocketConnectException and inspect response

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/errors.md

Use this example to catch a WebsocketConnectException from connect() and inspect the failed HTTP response. The exception extends HttpException, so a catch (HttpException) also matches it. The response is always attached and accessible via getResponse().

```php
use Amp\Websocket\Client\WebsocketConnectException;
use function Amp\Websocket\Client\connect;

try {
    $connection = connect('ws://localhost:1337/websocket');
} catch (WebsocketConnectException $exception) {
    $response = $exception->getResponse();
    printf("Handshake failed (HTTP %d %s): %s\n",
        $response->getStatus(), $response->getReason(), $exception->getMessage());
}
```

--------------------------------

### Catch Error from WebsocketHandshake header validation

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/errors.md

Catches \Error raised when a header name is empty or starts with a colon. The example uses ':invalid' to trigger the error and prints the message.

```php
try {
    $handshake = (new WebsocketHandshake('ws://example.com/'))->withHeader(':invalid', 'x');
} catch (\Error $exception) {
    printf("Bad header name: %s\n", $exception->getMessage());
}
```

--------------------------------

### Connect to a WebSocket server

Source: https://github.com/amphp/websocket-client/blob/2.x/README.md

Create a WebSocket connection using the connect() function and iterate over incoming messages.

```php
<?php

require 'vendor/autoload.php';

use function Amp\Websocket\Client\connect;

// Amp\Websocket\Client\connect() uses the WebsocketConnection instance
// defined by Amp\Websocket\Client\websocketConnector()
$connection = connect('ws://localhost:1337/websocket');

foreach ($connection as $message) {
    // $message is an instance of Amp\Websocket\WebsocketMessage
}
```

--------------------------------

### connect()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/functions.md

Establishes a WebSocket connection to the specified endpoint. The connection is fully established and the handshake validated before the function returns.

```APIDOC
## connect()

### Description
Establishes a WebSocket connection to the specified endpoint. The connection is fully established and the handshake validated before the function returns.

### Signature
```php
function connect(
    WebsocketHandshake|PsrUri|string $handshake,
    ?Cancellation $cancellation = null,
): WebsocketConnection
```

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `$handshake` | `WebsocketHandshake \| PsrUri \| string` | yes | — | The WebSocket endpoint. A `string` or `Psr\Http\Message\UriInterface` (league/uri) URI must use the `ws` or `wss` scheme; a `WebsocketHandshake` allows custom headers, query parameters and timeouts. |
| `$cancellation` | `?Cancellation` | no | `null` | An `Amp\Cancellation` that can cancel the connection attempt while it is in progress. |

### Return Type
`WebsocketConnection` (concretely an `Rfc6455Connection`). The connection is fully established — the handshake has been validated — before it is returned.

### Behavior
- If `$handshake` is not already a `WebsocketHandshake`, it is wrapped: `$handshake = new WebsocketHandshake($handshake);`
- Delegates to the global connector: `return websocketConnector()->connect($handshake, $cancellation);`

### Throws

| Error type | Condition |
|---|---|
| `WebsocketConnectException` | The HTTP response is invalid for an upgrade (for example a non-101 status, a missing/incorrect `upgrade` response header, or an invalid `sec-websocket-accept` header). See [`api-reference/WebsocketConnectException.md`](WebsocketConnectException.md). |
| `Amp\Http\Client\HttpException` | The underlying HTTP request fails (transport error, timeout, etc.). |
| `\ValueError` | The URI string cannot be parsed or its scheme is not `ws`/`wss` (raised by `WebsocketHandshake::__construct`). |

### Examples

Basic connection and message iteration:

```php
require 'vendor/autoload.php';

use function Amp\Websocket\Client\connect;

$connection = connect('ws://localhost:1337/websocket');

foreach ($connection as $message) {
    // $message is an instance of Amp\Websocket\WebsocketMessage
    printf("Received: %s\n", $message->buffer());
}
```

Connection with a handshake (custom headers), cancellation, and error handling:

```php
use Amp\TimeoutCancellation;
use Amp\Websocket\Client\WebsocketConnectException;
use Amp\Websocket\Client\WebsocketHandshake;
use Amp\Http\Client\HttpException;
use function Amp\Websocket\Client\connect;

$handshake = (new WebsocketHandshake('wss://libwebsockets.org'))
    ->withHeader('Sec-WebSocket-Protocol', 'dumb-increment-protocol');

try {
    $connection = connect($handshake, new TimeoutCancellation(5));
    $connection->sendText('Hello');
} catch (WebsocketConnectException $exception) {
    // The server responded, but not with a valid 101 Switching Protocols handshake.
    printf("Handshake rejected with HTTP status %d\n", $exception->getResponse()->getStatus());
} catch (HttpException $exception) {
    // The HTTP request itself failed (connection refused, TLS failure, timeout...).
    printf("HTTP failure: %s\n", $exception->getMessage());
}
```
```

--------------------------------

### Rfc6455Connector constructor signature

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Constructor for Rfc6455Connector with optional dependencies: connectionFactory, httpClient, and compressionContextFactory. Defaults create a fresh HTTP client with unlimited pool and TCP_NODELAY, and enable permessage-deflate compression if zlib is loaded.

```php
public function __construct(
    private readonly WebsocketConnectionFactory $connectionFactory = new Rfc6455ConnectionFactory(),
    ?HttpClient $httpClient = null,
    private readonly ?WebsocketCompressionContextFactory $compressionContextFactory = new Rfc7692CompressionFactory(),
) {
```

--------------------------------

### Activating the custom factory with Rfc6455Connector

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455ConnectionFactory.md

Shows how to wrap the custom factory in a connector and establish a WebSocket connection. The connector is created with the custom factory and then used to connect to a WebSocket endpoint.

```php
use Amp\Websocket\Client\Rfc6455Connector;
use Amp\Websocket\Client\WebsocketHandshake;

$connector = new Rfc6455Connector(connectionFactory: new LoggingConnectionFactory());
$connection = $connector->connect(new WebsocketHandshake('wss://example.com/socket'));
```

--------------------------------

### withTcpConnectTimeout usage example

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Sets the TCP connection timeout to 5 seconds.

```php
$handshake = (new WebsocketHandshake('ws://example.com/socket'))->withTcpConnectTimeout(5.0);
```

--------------------------------

### Custom connection parameters with WebsocketConnectionFactory

Source: https://github.com/amphp/websocket-client/blob/2.x/README.md

Configure a custom connection factory with heartbeat, rate limit, parser, and close period, then connect using a WebsocketConnector.

```php
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\Client\Rfc6455Connector;
use Amp\Websocket\Client\WebsocketHandshake;
use Amp\Websocket\ConstantRateLimit;
use Amp\Websocket\Parser\Rfc6455ParserFactory;
use Amp\Websocket\PeriodicHeartbeatQueue;

$connectionFactory = new Rfc6455ConnectionFactory(
    heartbeatQueue: new PeriodicHeartbeatQueue(
        heartbeatPeriod: 5, // 5 seconds
    ),
    rateLimit: new ConstantRateLimit(
        bytesPerSecondLimit: 2 ** 17, // 128 KiB
        framesPerSecondLimit: 10,
    ),
    parserFactory: new Rfc6455ParserFactory(
        messageSizeLimit: 2 ** 20, // 1 MiB
    ),
    frameSplitThreshold: 2 ** 14, // 16 KiB
    closePeriod: 0.5, // 0.5 seconds
);

$connector = new Rfc6455Connector($connectionFactory);

$handshake = new WebsocketHandshake('wss://example.com/websocket');
$connection = $connector->connect($handshake);
```

--------------------------------

### connect()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/functions.md

Opens a WebSocket connection using the global connector. Accepts a handshake object, PSR-7 URI, or string URI, and an optional cancellation token.

```APIDOC
## `connect()`

### Description
Opens a WebSocket connection using the global connector. Accepts a handshake object, PSR-7 URI, or string URI, and an optional cancellation token.

### Method
Function call

### Endpoint
`Amp\Websocket\Client\connect(WebsocketHandshake|PsrUri|string $handshake, ?Cancellation $cancellation = null): WebsocketConnection`

### Parameters
#### Function Parameters
- **$handshake** (`WebsocketHandshake|PsrUri|string`) - Required - The WebSocket handshake object, PSR-7 URI, or string URI to connect to.
- **$cancellation** (`?Cancellation`) - Optional - A cancellation token to cancel the connection attempt.

### Return Type
`WebsocketConnection` — the established WebSocket connection.

### Description
This function uses the global connector obtained via `websocketConnector()` to establish the connection. It is the primary entry point for opening WebSocket connections in applications.
```

--------------------------------

### WebsocketConnector::connect()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/types.md

Establishes a WebSocket connection from a WebsocketHandshake. Throws HttpException on request failure or WebsocketConnectException on invalid/non-101 response.

```APIDOC
## [POST] connect()

### Description
Establishes a WebSocket connection from a WebsocketHandshake. Throws HttpException on request failure or WebsocketConnectException on invalid/non-101 response.

### Method
POST

### Endpoint
`WebsocketConnector::connect(WebsocketHandshake $handshake, ?Cancellation $cancellation = null)`

### Parameters
#### Request Body
- **$handshake** (WebsocketHandshake) - Required - Describes the endpoint and handshake parameters.
- **$cancellation** (?Cancellation) - Optional - Can abort the connection attempt.

### Response
#### Success Response (200)
- **WebsocketConnection** - The established WebSocket connection.

#### Error Handling
- **HttpException** - Thrown if the request fails.
- **WebsocketConnectException** - Thrown if the response is invalid or not a 101 switching protocols response.
```

--------------------------------

### WebsocketHandshake::withHeaders()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/errors.md

Replaces all headers with the given array. Throws \Error if any header name is empty or starts with a colon.

```APIDOC
## [METHOD] WebsocketHandshake::withHeaders()

### Description
Replaces all headers with the given array. Throws \Error if any header name is empty or starts with a colon.

### Method
withHeaders

### Endpoint
`withHeaders(array $headers): WebsocketHandshake`

### Parameters
#### Method Parameters
- **$headers** (array) - Required - Associative array of header names to values.

### Request Example
```php
$handshake = (new WebsocketHandshake('ws://example.com/'))->withHeaders(['X-Foo' => 'bar']);
```

### Response
#### Success Response
- Returns a new `WebsocketHandshake` instance with the updated headers.

#### Error Response
- **\Error** - If any header name is empty or starts with a colon. Message: `Header name cannot be empty or start with a colon (:)`.

### Error Handling
Catch `\Error` to handle invalid header names.

```php
try {
    $handshake = (new WebsocketHandshake('ws://example.com/'))->withHeader(':invalid', 'x');
} catch (\Error $exception) {
    printf("Bad header name: %s\n", $exception->getMessage());
}
```
```

--------------------------------

### Amp\Websocket\Client\connect()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/README.md

Convenience function that establishes a WebSocket connection using the global connector. It builds a handshake from the given URI and optional options, then returns a WebsocketConnection.

```APIDOC
## connect()

### Description
Convenience function that establishes a WebSocket connection using the global connector. It builds a handshake from the given URI and optional options, then returns a WebsocketConnection.

### Signature
`Amp\Websocket\Client\connect(string|Psr\Http\Message\UriInterface $uri, ?WebsocketHandshake $handshake = null, ?WebsocketConnector $connector = null): WebsocketConnection`

### Parameters
- **$uri** (string|Psr\Http\Message\UriInterface) - Required - The WebSocket URI (ws:// or wss://) to connect to.
- **$handshake** (?WebsocketHandshake) - Optional - Custom handshake object; if null, a default handshake is created from the URI.
- **$connector** (?WebsocketConnector) - Optional - Custom connector; if null, the global connector is used.

### Return Value
- **WebsocketConnection** - The established WebSocket connection.

### Exceptions
- **WebsocketConnectException** - Thrown if the connection fails.
```

--------------------------------

### Constructor: Rfc6455ConnectionFactory::__construct

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455ConnectionFactory.md

Creates a new Rfc6455ConnectionFactory instance with optional configuration for heartbeat, rate limiting, parser factory, frame split threshold, and close period.

```APIDOC
## Constructor: Rfc6455ConnectionFactory::__construct

### Description
Creates a new Rfc6455ConnectionFactory instance with optional configuration for heartbeat, rate limiting, parser factory, frame split threshold, and close period.

### Method
Constructor

### Signature
```php
public function __construct(
    private readonly ?WebsocketHeartbeatQueue $heartbeatQueue = null,
    private readonly ?WebsocketRateLimit $rateLimit = null,
    private readonly WebsocketParserFactory $parserFactory = new Rfc6455ParserFactory(
        messageSizeLimit: Rfc6455Connection::DEFAULT_MESSAGE_SIZE_LIMIT,
        frameSizeLimit: Rfc6455Connection::DEFAULT_FRAME_SIZE_LIMIT,
    ),
    private readonly int $frameSplitThreshold = Rfc6455Client::DEFAULT_FRAME_SPLIT_THRESHOLD,
    private readonly float $closePeriod = Rfc6455Client::DEFAULT_CLOSE_PERIOD,
)
```

### Parameters
- `$heartbeatQueue` (?WebsocketHeartbeatQueue) - Optional - A queue generating periodic heartbeat (ping) frames for the connection. Use e.g. `Amp\Websocket\PeriodicHeartbeatQueue` to enable automatic pings.
- `$rateLimit` (?WebsocketRateLimit) - Optional - Limits the data/frame rate of received messages (e.g. `Amp\Websocket\ConstantRateLimit` with `bytesPerSecondLimit` and/or `framesPerSecondLimit`).
- `$parserFactory` (WebsocketParserFactory) - Optional - Creates the frame/message parser. The default is an RFC 6455 parser with 10 MiB message and frame size limits (see `Rfc6455Connection` constants).
- `$frameSplitThreshold` (int) - Optional - Number of payload bytes after which outgoing data frames are split into multiple frames. The value of the default is defined in `amphp/websocket` (`Rfc6455Client`).
- `$closePeriod` (float) - Optional - Seconds to wait between sending the close frame and closing the socket. The value of the default is defined in `amphp/websocket` (`Rfc6455Client`).

### Example
```php
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\ConstantRateLimit;
use Amp\Websocket\Parser\Rfc6455ParserFactory;
use Amp\Websocket\PeriodicHeartbeatQueue;

$connectionFactory = new Rfc6455ConnectionFactory(
    heartbeatQueue: new PeriodicHeartbeatQueue(
        heartbeatPeriod: 5, // 5 seconds
    ),
    rateLimit: new ConstantRateLimit(
        bytesPerSecondLimit: 2 ** 17, // 128 KiB
        framesPerSecondLimit: 10,
    ),
    parserFactory: new Rfc6455ParserFactory(
        messageSizeLimit: 2 ** 20, // 1 MiB
    ),
    frameSplitThreshold: 2 ** 14, // 16 KiB
    closePeriod: 0.5, // 0.5 seconds
);
```
```

--------------------------------

### Rfc6455Connector::__construct

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Creates a new Rfc6455Connector instance with configurable connection factory, HTTP client, and compression context factory. This constructor allows customization of connection behavior, HTTP transport, and permessage-deflate compression negotiation.

```APIDOC
## Rfc6455Connector::__construct

### Description
Creates a new Rfc6455Connector instance with configurable connection factory, HTTP client, and compression context factory. This constructor allows customization of connection behavior, HTTP transport, and permessage-deflate compression negotiation.

### Method
Constructor

### Signature
```php
public function __construct(
    private readonly WebsocketConnectionFactory $connectionFactory = new Rfc6455ConnectionFactory(),
    ?HttpClient $httpClient = null,
    private readonly ?WebsocketCompressionContextFactory $compressionContextFactory = new Rfc7692CompressionFactory(),
)
```

### Parameters
- **connectionFactory** (WebsocketConnectionFactory) - Optional - Default: `new Rfc6455ConnectionFactory()` - Turns the validated 101 response + raw socket into a `WebsocketConnection`. Replace to customize connection behavior (e.g. a subclass or delegate wrapping `Rfc6455ConnectionFactory`).
- **httpClient** (?HttpClient) - Optional - Default: `null` - Amp HTTP client used for the upgrade request. When `null`, a fresh default is built: `(new HttpClientBuilder)->usingPool(new UnlimitedConnectionPool(new DefaultConnectionFactory(connectContext: (new ConnectContext)->withTcpNoDelay())))->build()` — unlimited connection pool, TCP_NODELAY enabled. Supply your own to reuse pools, configure TLS/proxy, or apply interceptors.
- **compressionContextFactory** (?WebsocketCompressionContextFactory) - Optional - Default: `new Rfc7692CompressionFactory()` - Negotiates permessage-deflate (RFC 7692) compression. `null` disables compression. Request-side negotiation is only attempted when this is non-`null` **and** the `zlib` PHP extension is loaded (`\extension_loaded('zlib')`, `src/Rfc6455Connector.php:116`).

### Example
```php
use Amp\Http\Client\HttpClientBuilder;
use Amp\Websocket\Client\Rfc6455ConnectionFactory;
use Amp\Websocket\Client\Rfc6455Connector;

$httpClient = (new HttpClientBuilder)->build(); // shared transport

$connector = new Rfc6455Connector(
    connectionFactory: new Rfc6455ConnectionFactory(closePeriod: 1.0),
    httpClient: $httpClient,
    compressionContextFactory: null, // no permessage-deflate
);
```
```

--------------------------------

### Catch ValueError from WebsocketHandshake constructor

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/errors.md

Catches \ValueError raised when the URI is invalid or the scheme is not ws/wss. The example uses 'http' to trigger the error and prints the message.

```php
use Amp\Websocket\Client\WebsocketHandshake;

try {
    $handshake = new WebsocketHandshake('http://example.com/websocket'); // 'http' is rejected
} catch (\ValueError $exception) {
    printf("Invalid WebSocket URI: %s\n", $exception->getMessage());
}
```

--------------------------------

### Rfc6455Connection::__construct

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Creates a new Rfc6455Connection instance. This constructor is typically called by the connection factory, not directly by application code.

```APIDOC
## Constructor

### Signature
```php
public function __construct(
    private readonly Rfc6455Client $client,
    private readonly Response $handshakeResponse,
)
```

### Parameters
- **$client** (Amp\Websocket\Rfc6455Client) - Required - The underlying RFC 6455 protocol client.
- **$handshakeResponse** (Amp\Http\Client\Response) - Required - The server response that originated the client connection.

### Description
Creates a new Rfc6455Connection instance. This constructor is typically called by the connection factory, not directly by application code.
```

--------------------------------

### Constructor signature for Rfc6455Connection

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Constructor that takes an Rfc6455Client and a Response object. Instances are normally created by Rfc6455ConnectionFactory::createConnection(), not directly by application code.

```php
public function __construct(
    private readonly Rfc6455Client $client,
    private readonly Response $handshakeResponse,
) {
```

--------------------------------

### withQueryParameters(array $params)

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Replaces all query parameters of the target URI. Returns a clone of the handshake instance.

```APIDOC
## Method: `withQueryParameters(array $params)`

### Description
Replaces all query parameters of the target URI. Returns a clone of the handshake instance.

### Parameters
- **params** (`array` of `QueryArrayType`) - Required - Array of query parameters.

### Returns
- Returns a clone of the `WebsocketHandshake` instance with the updated query parameters.

### Example
```php
$handshake = $handshake->withQueryParameters(['room' => 'lobby']);
```
```

--------------------------------

### withHeader(string $name, string|array $value): self

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Replaces the given header in the returned clone. The value can be a single string or an array of values. Throws an \Error if the header name is empty or starts with a colon.

```APIDOC
## withHeader(string $name, string|array $value): self

### Description
Replaces the given header in the returned clone of the WebsocketHandshake object.

### Method
withHeader

### Signature
public function withHeader(string $name, string|array $value): self

### Parameters
- **$name** (string) - Required - Header name.
- **$value** (string|array) - Required - Header value or array of values.

### Returns
- **self** - A clone of the WebsocketHandshake with the updated header.

### Errors
- Throws \Error if the header name is empty or starts with a colon.

### Example
```php
$handshake = (new WebsocketHandshake('ws://example.com/socket'))->withHeader('Origin', 'http://localhost:1337');
```
```

--------------------------------

### getTlsInfo(): ?TlsInfo - Method Signature

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Returns Amp\Socket\TlsInfo describing the TLS session for wss:// connections, or null for plain ws:// connections.

```php
public function getTlsInfo(): ?TlsInfo
```

--------------------------------

### getTlsInfo(): ?TlsInfo

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connection.md

Returns TLS information for wss:// connections, or null for plain ws:// connections.

```APIDOC
## getTlsInfo(): ?TlsInfo

### Description
Returns `Amp\Socket\TlsInfo` describing the TLS session for `wss://` connections, or `null` for plain `ws://` connections.

### Return
- **?TlsInfo** - TLS session info, or null if not using TLS.
```

--------------------------------

### new WebsocketHandshake(PsrUri|string $uri, array $headers = [])

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Creates a new WebsocketHandshake instance for configuring a WebSocket client connection. The constructor accepts the target URI and optional initial handshake headers.

```APIDOC
## Constructor: `new WebsocketHandshake(PsrUri|string $uri, array $headers = [])`

### Description
Creates a new WebsocketHandshake instance for configuring a WebSocket client connection.

### Parameters
- **uri** (`PsrUri|string`) - Required - Target endpoint; must use scheme `ws` or `wss`. Strings are parsed with `League\Uri\Http::new()`.
- **headers** (`array` of `HeaderParamArrayType`) - Optional - Initial handshake headers. Defaults to `[]`.

### Example
```php
use Amp\Websocket\Client\WebsocketHandshake;

$handshake = new WebsocketHandshake(
    'wss://example.com/socket?room=lobby',
    ['Origin' => 'https://example.com']
);
```
```

--------------------------------

### Basic connection and message iteration

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/functions.md

Connects to a WebSocket endpoint and iterates over incoming messages. Requires the autoloader and imports the connect function. Each message is an Amp\Websocket\WebsocketMessage.

```php
require 'vendor/autoload.php';

use function Amp\Websocket\Client\connect;

$connection = connect('ws://localhost:1337/websocket');

foreach ($connection as $message) {
    // $message is an instance of Amp\Websocket\WebsocketMessage
    printf("Received: %s\n", $message->buffer());
}
```

--------------------------------

### connect(WebsocketHandshake $handshake, ?Cancellation $cancellation = null): WebsocketConnection

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/Rfc6455Connector.md

Establishes a WebSocket connection using the RFC6455 handshake. This method blocks until the upgrade succeeds and returns a fully validated WebSocketConnection.

```APIDOC
## connect(WebsocketHandshake $handshake, ?Cancellation $cancellation = null): WebsocketConnection

### Description
Establishes a WebSocket connection using the RFC6455 handshake. This method blocks until the upgrade succeeds and returns a fully validated WebSocketConnection.

### Method
connect

### Signature
```php
public function connect(WebsocketHandshake $handshake, ?Cancellation $cancellation = null): WebsocketConnection
```

### Parameters
- `$handshake` (WebsocketHandshake) - Required - Immutable handshake builder describing the endpoint, headers, query parameters and timeouts.
- `$cancellation` (?Cancellation) - Optional - Cancellation token; cancelling it aborts the connection attempt.

### Return Type
`WebsocketConnection` - a fully validated, connected WebSocket client. The method blocks (fiber suspension) until the upgrade has succeeded; the returned connection is guaranteed to have a valid 101 handshake.

### Behavior
1. Generates a random key: `$key = Websocket\generateKey();`
2. Builds the HTTP request via `generateRequest($handshake, $key)` (private, `src/Rfc6455Connector.php:102`):
   - URI scheme rewritten: `wss` → `https`, `ws` → `http` (`$uri->withScheme($uri->getScheme() === 'wss' ? 'https' : 'http')`).
   - HTTP method `GET`; headers copied from `$handshake->getHeaders()`.
   - `setTcpConnectTimeout($handshake->getTcpConnectTimeout())`, `setTlsHandshakeTimeout($handshake->getTlsHandshakeTimeout())`, `setHeaderSizeLimit($handshake->getHeaderSizeLimit())`.
   - `sec-websocket-extensions`: existing handshake extensions are kept; if `$this->compressionContextFactory` is non-`null` and the `zlib` extension is loaded, `$this->compressionContextFactory->createRequestHeader()` is appended. Header set only if non-empty.
   - `setProtocolVersions(['1.1'])`, `connection: Upgrade`, `upgrade: websocket`, `sec-websocket-version: 13`, `sec-websocket-key: $key`.
3. Registers an upgrade handler (`$request->setUpgradeHandler(...)`). When the HTTP client accepts the upgrade, the handler runs and:
   - Rejects with `WebsocketConnectException('Upgrade header does not equal "websocket"', $response)` if `strtolower($response->getHeader('upgrade') ?? '') !== 'websocket'`.
   - Rejects with `WebsocketConnectException('Invalid Sec-WebSocket-Accept header', $response)` if `Websocket\validateAcceptForKey($response->getHeader('sec-websocket-accept') ?? '', $key)` fails.
   - Iterates `Http\splitHeader($response, 'sec-websocket-extensions') ?? []`; the first extension for which `$compressionContextFactory?->fromServerHeader($extension)` returns a context wins.
   - Completes the deferred future with `$connectionFactory->createConnection($response, $socket, $compressionContext ?? null)`.
4. Sends the request: `$response = $this->httpClient->request($request, $cancellation); try { ... } catch { ... }` — the response is awaited first.
5. If `$response->getStatus() !== Http\HttpStatus::SWITCHING_PROTOCOLS` (101), throws:

   ```php
   throw new WebsocketConnectException(\sprintf(
       'A %s (%d) response was not received; instead received response status: %s (%d)',
       Http\HttpStatus::getReason(Http\HttpStatus::SWITCHING_PROTOCOLS),
       Http\HttpStatus::SWITCHING_PROTOCOLS,
       $response->getReason(),
       $response->getStatus()
   ), $response);
   ```
6. Returns `$deferred->getFuture()->await()`, i.e. the `WebsocketConnection` produced by the connection factory.

### Throws
- `WebsocketConnectException` - Response status is not 101; or the upgrade response header is missing/not `websocket`; or `sec-websocket-accept` is invalid. The failing `Response` is available via `getResponse()`.
- `Amp\Http\Client\HttpException` - The HTTP request itself fails (network, TLS, timeouts — including cancellation via `$cancellation`).
```

--------------------------------

### Amp\Websocket\Client\websocketConnector()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/README.md

Returns the global per-event-loop connector instance, creating it if necessary. This connector is used by connect() and can be customized.

```APIDOC
## websocketConnector()

### Description
Returns the global per-event-loop connector instance, creating it if necessary. This connector is used by connect() and can be customized.

### Signature
`Amp\Websocket\Client\websocketConnector(): WebsocketConnector`

### Return Value
- **WebsocketConnector** - The global connector instance.
```

--------------------------------

### new WebsocketHandshake(PsrUri|string $uri, array $headers = [])

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/api-reference/WebsocketHandshake.md

Creates a new immutable WebSocket opening handshake builder. The constructor parses the target URI (must use ws or wss scheme) and optionally accepts initial HTTP headers for the handshake.

```APIDOC
## Constructor

### Description
Creates a new immutable WebSocket opening handshake builder. The constructor parses the target URI (must use ws or wss scheme) and optionally accepts initial HTTP headers for the handshake.

### Signature
```php
public function __construct(PsrUri|string $uri, array $headers = [])
```

### Parameters
- **$uri** (PsrUri|string) - Required - Target address of websocket (e.g. ws://foo.bar/bar or wss://crypto.example/?secureConnection) or a PsrUri instance. A string is parsed with `League\Uri\Http::new($uri)`; it must use scheme `ws` or `wss`.
- **$headers** (array) - Optional - Initial HTTP headers for the opening handshake. Default: `[]`.

### Throws
- **\ValueError** - If the URI string cannot be parsed at all (message: `Invalid Websocket URI provided`).
- **\ValueError** - If the parsed URI uses any other scheme (e.g. `http`) (message: `The URI scheme must be ws or wss, got "..."`).

### Example
```php
use Amp\Websocket\Client\WebsocketHandshake;

$handshake = new WebsocketHandshake(
    'wss://example.com/websocket?token=abc',
    ['Origin' => 'https://example.com'],
);
```
```

--------------------------------

### withoutQuery()

Source: https://github.com/amphp/websocket-client/blob/2.x/_autodocs/configuration.md

Removes all query parameters from the target URI. Returns a clone of the handshake instance.

```APIDOC
## Method: `withoutQuery()`

### Description
Removes all query parameters from the target URI. Returns a clone of the handshake instance.

### Returns
- Returns a clone of the `WebsocketHandshake` instance without any query parameters.

### Example
```php
$handshake = $handshake->withoutQuery();
```
```
Tokens:
Raw