phpcent

https://github.com/centrifugal/phpcent
Admin
phpcent is a PHP library that enables communication with Centrifugo v5 HTTP API for real-time...
Tokens:29,497
Snippets:225
Trust Score:9.6
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### info usage example

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Example call to get server info.

```php
$info = $client->info();
```

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

### channels usage examples

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Example calls to get all active channels, with and without a pattern filter.

```php
$channels = $client->channels();
```

```php
$channels = $client->channels("news:*");
```

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

### Install phpcent with Composer

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Install the phpcent library via Composer. Requires Composer and a supported PHP version.

```bash
composer require centrifugal/phpcent:~6.0
```

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

### Basic publish example

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Creates a phpcent Client, sets the API key, and publishes a simple message to a channel. The response is returned as mixed.

```php
$client = new \phpcent\Client("http://localhost:8000/api");
$client->setApiKey("Centrifugo API key");
$client->publish("channel", ["message" => "Hello World"]);
```

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

### Run PHPUnit tests with Docker

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Commands to install dependencies, start a Centrifugo server in Docker, run the PHPUnit test suite, and stop the container. The tests assume a local Centrifugo server on port 8000.

```shell
# Install package dependencies.
$ composer install

# The following command starts a Centrifugo server running in a background Docker container.
$ docker run -d -p 8000:8000 --name centrifugo centrifugo/centrifugo centrifugo --api_insecure

# Run the test suite.
$ vendor/bin/phpunit

# Shut down the Centrifugo container.
$ docker stop centrifugo
```

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

### setSafety: Example with error handling

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Creates a client with setSafety(false) and publishes a message, catching exceptions for json_decode errors or non-200 HTTP responses.

```php
try {
    $client = new \phpcent\Client("https://localhost:8000/api");
    $client->setSafety(false);
    $client->publish("channel", ["message" => "Hello World"]);
} catch (\Exception $e) {
    // json_decode error, or non-200 HTTP response (see errors.md)
    error_log($e->getMessage());
}
```

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

### setCert usage example

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Creates a Client and sets a PEM CA certificate bundle path via setCert. The certificate must match the host name in the Client URL.

```php
$client = new \phpcent\Client("https://localhost:8000/api");
$client->setCert("/path/to/certificate.pem");
```

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

### info

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Gets server info. No parameters; the request body is an empty JSON object.

```APIDOC
## info

### Description
Get server info.

### Method
POST

### Endpoint
/info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
{}

### Response
#### Success Response (200)
- **result** (object) - Decoded JSON response; the test suite asserts `$res->result->nodes` is an array.

#### Response Example
{
  "result": {
    "nodes": []
  }
}

```

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

### setCAPath usage example

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Creates a Client, sets a certificate bundle with setCert, then sets a CA directory path with setCAPath. Both are applied as cURL options when safety is enabled.

```php
$client = new \phpcent\Client("https://localhost:8000/api");
$client->setCert("/path/to/certificate.pem");
$client->setCAPath("/ca/path");
```

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

### info method signature

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Method signature for getting server info. No parameters; the request body is an empty JSON object.

```php
public function info()
```

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

### Fully configured phpcent client with fluent setters

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/configuration.md

Fully configured phpcent client example. It sets TLS CA bundle and directory, connect and total timeouts, associative array decoding, and IPv4-only DNS resolution. The publish call sends a message to a channel. Note that setCert and setCAPath only take effect when safety is enabled (default true).

```php
$client = new \phpcent\Client("https://localhost:8000/api", "<API key>", "<secret key>");
$client
    ->setCert("/path/to/certificate.pem")     // TLS: CA bundle (safety must stay true)
    ->setCAPath("/ca/path")                   // TLS: CA directory
    ->setConnectTimeoutOption(5)              // 5s connect timeout
    ->setTimeoutOption(15)                    // 15s total timeout
    ->setUseAssoc(true)                       // decode responses as arrays
    ->forceIpResolveV4();                     // IPv4-only DNS resolution

$res = $client->publish("channel", ["message" => "Hello World"]);
```

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

### POST /api/channels

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Get list of active channels.

```APIDOC
## [POST] /api/channels

### Description
Get list of active channels.

### Method
POST

### Endpoint
/api/channels

### Parameters
None

### Request Example
{}

### Response
#### Success Response (200)
- **error** (object) - Error object
- **result** (object) - Result object

#### Response Example
{
  "error": null,
  "result": {}
}
```

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

### historyRemove usage example

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Example call to remove history for the 'news' channel.

```php
$client->historyRemove("news");
```

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

### Client::disconnect() with Disconnect object

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

Example call to Client::disconnect() with a Disconnect object. The disconnect is sent only when the array is non-empty.

```php
$client->disconnect("user-42", "", ["code" => 3001, "reason" => "maintenance"]);
```

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

### presenceStats method signature and usage

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Defines the presenceStats method signature and shows how to call it to get channel presence stats. Maps to the presence_stats API command and always sends the channel. Returns a decoded JSON response and throws \Exception on error.

```php
public function presenceStats($channel)
```

```php
$stats = $client->presenceStats("news");
```

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

### disconnect user with options

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

For disconnecting a user via the client API. The method signature shows optional $disconnect, $whitelist, and $session parameters; the base payload always includes user and client. The second example disconnects a single user, while the third demonstrates passing a disconnect object, whitelist channels, and a session, all optional and sent only if non-empty.

```php
public function disconnect($user, $client = '', $disconnect = array(), $whitelist = array(), $session = '')
```

```php
$client->disconnect("user-42");
```

```php
$client->disconnect(
    "user-42",
    "",
    ["code" => 3001, "reason" => "maintenance"],  // disconnect
    ["chat:lobby"],                                // whitelist channels
    "session-a"                                    // session
);
```

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

### DNS resolution timeout error

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Example error message indicating DNS resolution timeout, possibly due to IPv6 resolution issues.

```text
cURL error: Resolving timed out after [value] milliseconds
```

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

### history

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Get channel history. Supports pagination, recovery cursor, and reverse order.

```APIDOC
## history

### Description
Get channel history.

### Method
history

### Endpoint
history($channel, $limit = 0, $since = array(), $reverse = false)

### Parameters
#### Path Parameters
- **$channel** (string) - Required - Channel name

#### Query Parameters
- **$limit** (int) - Optional - Pagination limit; always sent (default `0` per source)
- **$since** (array) - Optional - [StreamPosition](../types.md#streamposition) `['offset' => int, 'epoch' => string]` used as the recovery cursor; sent as `since` only if non-empty
- **$reverse** (boolean) - Optional - Return history in reverse order; always sent

### Request Example
```php
$history = $client->history("news");
```

```php
// Recovery-style pagination: get up to 100 messages published after a given offset.
$history = $client->history("news", 100, ["offset" => 52, "epoch" => "abc"], false);
```

### Response
#### Success Response
- **mixed** - Decoded JSON response.

### Throws
- `\Exception` - As documented in errors.md.
```

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

### history method signature and usage

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Defines the history method signature and shows two usage examples: a basic call and a recovery-style pagination call. The method always sends channel, limit, and reverse; the since parameter is sent only if non-empty. Returns a decoded JSON response and throws \Exception on error.

```php
public function history($channel, $limit = 0, $since = array(), $reverse = false)
```

```php
$history = $client->history("news");
```

```php
// Recovery-style pagination: get up to 100 messages published after a given offset.
$history = $client->history("news", 100, ["offset" => 52, "epoch" => "abc"], false);
```

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

### channels method signature

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Method signature for getting all active channels. The $pattern parameter is optional and defaults to an empty string; it is always sent in the payload.

```php
public function channels($pattern = '')
```

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

### presence

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Get channel presence info. This method retrieves per-client presence data for a given channel.

```APIDOC
## presence

### Description
Get channel presence info.

### Method
presence

### Endpoint
presence($channel)

### Parameters
#### Path Parameters
- **$channel** (string) - Required - Channel name

### Request Example
```php
$presence = $client->presence("news");
```

### Response
#### Success Response
- **mixed** - Decoded JSON response (envelope `result` contains per-client presence data on the server side).

### Throws
- `\Exception` - As documented in errors.md.
```

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

### presence method signature and usage

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Defines the presence method signature and shows how to call it to get channel presence info. The payload always includes the channel. Returns a decoded JSON response and throws \Exception on error.

```php
public function presence($channel)
```

```php
$presence = $client->presence("news");
```

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

### channels

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Gets all active channels, optionally filtered by a pattern. Sends the 'channels' API command with the pattern payload.

```APIDOC
## channels

### Description
Get all active channels.

### Method
POST

### Endpoint
/channels

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pattern** (string) - Optional - Channel pattern to filter the result; always sent (empty string by default)

### Request Example
{
  "pattern": "news:*"
}

### Response
#### Success Response (200)
- **result** (object) - Decoded JSON response

#### Response Example
{
  "result": {}
}

```

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

### setConnectTimeoutOption usage example

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Sets the connection timeout to 0 seconds, meaning the option is never set (never timeout). The value is applied as CURLOPT_CONNECTTIMEOUT only when truthy.

```php
$client->setConnectTimeoutOption(0); // Seconds | 0 = never
```

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

### Catch \Exception from API calls

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/errors.md

Catch the built-in \Exception thrown by send() and request() for network failures, non-200 HTTP statuses, or undecodable JSON bodies. The example sets connect and timeout options before publishing and logs the exception message. Note that Centrifugo-level errors are not exceptions and must be handled via the response envelope.

```php
$client = new \phpcent\Client("http://localhost:8000/api");
$client->setApiKey("Centrifugo API key");

try {
    $client->setConnectTimeoutOption(5);
    $client->setTimeoutOption(15);
    $res = $client->publish("channel", ["message" => "Hello World"]);
} catch (\Exception $e) {
    // Network failure, non-200 status, or undecodable JSON body.
    error_log("Command failed: " . $e->getMessage());
}
```

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

### setTimeoutOption method and usage

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Sets the total request timeout in seconds, applied as CURLOPT_TIMEOUT only when truthy. Returns $this for fluent chaining. The example sets a 2-second timeout.

```php
public function setTimeoutOption($timeoutOption)
```

```php
$client->setTimeoutOption(2); // Seconds
```

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

### unsubscribe channel user

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

For unsubscribing a user from a channel via the client API. The method signature shows optional $client and $session parameters; the base payload always includes channel, user, and client. The second example unsubscribes a single user, while the third targets only a specific session, requiring the $client parameter to be passed as an empty string.

```php
public function unsubscribe($channel, $user, $client = '', $session = '')
```

```php
$client->unsubscribe("news", "user-42");
```

```php
// Only unsubscribe a specific session of the user.
$client->unsubscribe("news", "user-42", "", "session-a");
```

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

### Handle Centrifugo-level errors in response envelope

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/errors.md

Check the response envelope for an 'error' field after a publish call. Centrifugo returns HTTP 200 with an error field for command rejections (e.g. unknown channel, permission denied), which is decoded and returned normally, never thrown. The example prints the error code and message when present.

```php
$client = new \phpcent\Client("http://localhost:8000/api");
$client->setUseAssoc(true);

$res = $client->publish('namespace:unknown', ["message" => "Hello"]);
if (isset($res['error'])) {
    // e.g. ["code" => 102, "message" => "unknown channel"]
    printf("Centrifugo error %d: %s\n", $res['error']['code'], $res['error']['message']);
} else {
    // $res['result'] holds the command result
}
```

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

### publish with non-trivial options

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Publishes with skip history, tags, idempotency key, and version parameters. Demonstrates how to pass all optional arguments to the publish method.

```php
// Non-trivial options: skip history, attach tags, idempotency key, version.
$client->publish(
    "notifications",
    ["message" => "New version released"],
    true,                      // skipHistory
    ["lang" => "en"],          // tags
    "key-123",                 // idempotencyKey
    false,                     // delta
    42,                        // version
    "2024-01-01T00:00:00Z"     // versionEpoch
);
```

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

### All available API methods

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

List of all available API methods on the client. Each method returns a response object.

```php
$response = $client->publish($channel, $data);
$response = $client->broadcast($channels, $data);
$response = $client->subscribe($channel, $userId);
$response = $client->unsubscribe($channel, $userId);
$response = $client->disconnect($userId);
$response = $client->presence($channel);
$response = $client->presenceStats($channel);
$response = $client->history($channel);
$response = $client->historyRemove($channel);
$response = $client->channels();
$response = $client->info();
$response = $client->batch($data);
```

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

### Create client with API key and secret in constructor

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Create a client with API key and secret set in the constructor. This avoids separate setApiKey and setSecret calls.

```php
$client = new \phpcent\Client("http://localhost:8000/api", "<API key>", "<secret key>");
```

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

### Constructor

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Creates a new phpcent Client instance with the Centrifugo API endpoint, optional API key, and optional secret.

```APIDOC
## Constructor

### Description
Creates a new phpcent Client instance.

### Method
Constructor

### Signature
```php
public function __construct($url, $apikey = '', $secret = '')
```

### Parameters
- `$url` (string) - Required - Centrifugo API endpoint, e.g. `http://localhost:8000/api`
- `$apikey` (string) - Optional - Centrifugo API key, sent as `X-API-Key` header on every request; may be set later via `setApiKey()`
- `$secret` (string) - Optional - Centrifugo secret key used to HMAC-SHA256-sign JWTs; may be set later via `setSecret()`

### Return
A new `Client` instance.

### Throws
None.

### Example
```php
$client = new \phpcent\Client("http://localhost:8000/api");
```

```php
// API key and secret can also be provided up front.
$client = new \phpcent\Client("http://localhost:8000/api", "<API key>", "<secret key>");
```
```

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

### POST {url}/info

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Retrieves information about the server.

```APIDOC
## POST {url}/info

### Description
Retrieves information about the server.

### Method
POST

### Endpoint
{url}/info

### Parameters
#### Request Body
Empty object.

### Request Example
{}

### Response
#### Success Response (200)
- **result.nodes** (array) - Array of node information.

```

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

### Create a Client with API key and secret provided up front

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Passes the API key and secret directly to the constructor instead of setting them later. The API key is sent as the X-API-Key header on every request, and the secret is used to HMAC-SHA256-sign JWTs.

```php
// API key and secret can also be provided up front.
$client = new \phpcent\Client("http://localhost:8000/api", "<API key>", "<secret key>");
```

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

### Create a Client with default API key and secret

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Instantiates a new phpcent Client with only the Centrifugo API endpoint. The API key and secret are optional and default to empty strings.

```php
$client = new \phpcent\Client("http://localhost:8000/api");
```

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

### POST {url}/batch

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Executes multiple commands in a single request.

```APIDOC
## POST {url}/batch

### Description
Executes multiple commands in a single request.

### Method
POST

### Endpoint
{url}/batch

### Parameters
#### Request Body
- **commands** (array) - Required - Array of command objects, each with a method name as key and parameters as value.

### Request Example
{
  "commands": [
    {
      "<method>": {}
    }
  ]
}

### Response
#### Success Response (200)
- **replies** (array) - Array of replies from each command.

```

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

### phpcent\Client::__construct

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Constructor for the phpcent Client class.

```APIDOC
## Constructor

### Description
Creates a new phpcent Client instance with the specified Centrifugo server URL, API key, and secret.

### Signature
```php
public function __construct(string $url, string $apikey = '', string $secret = '')
```

### Parameters
- **$url** (string) - Required - The base URL of the Centrifugo server.
- **$apikey** (string) - Optional - The API key for authentication. Defaults to `''`.
- **$secret** (string) - Optional - The secret key for JWT token generation. Defaults to `''`.

### Returns
A new `phpcent\Client` instance.
```

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

### Generate connection token with 5-minute expiry

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Generate a connection token that expires after 5 minutes. The expiration time is passed as the second argument.

```php
$token = $client->setSecret("Centrifugo secret key")->generateConnectionToken($userId, time() + 5*60);
```

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

### batch

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

Documentation for the batch request payload accepted by Client::batch().

```APIDOC
## batch

### Description
Sends a batch request containing multiple commands to the server. The method accepts an array of commands and passes it through to the batch command unchanged.

### Method
`batch`

### Parameters
- **data** (array) - Required - An array containing a `commands` key with a list of command objects. Each command object has a single key equal to the API method name (e.g. `presence_stats`, `publish`) mapping to that command's params.

### Request Example
```php
[
    'commands' => [
        ['publish' => ['channel' => 'x:test2', 'data' => []]],
        // ...more commands
    ],
]
```

### Response
Returns a response envelope with a `replies` array containing the results of each command.
```

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

### StreamPosition array shape and usage in history()

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

The StreamPosition type is an associative array with 'offset' (int) and 'epoch' (string) fields. It is sent as 'recover_since' by Client::subscribe() and as 'since' by Client::history(), only when the array is non-empty. The example shows a call to history() with a StreamPosition value.

```php
// PHPDoc shape (associative array)
array $recoverSince = ['offset' => int, 'epoch' => string]
```

```php
$client->history("news", 100, ["offset" => 52, "epoch" => "abc"]);
```

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

### SubscribeOptionOverride array shape and usage in subscribe()

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

The SubscribeOptionOverride type is an associative array where each key is a Centrifugo subscription-option name mapped to an override object of the form ['value' => <bool/int/string>]. It is sent as 'override' by Client::subscribe() when non-empty. The example shows a subscribe() call with a presence override.

```php
// PHPDoc shape (associative array); each key is an option name mapped to a {"value": ...} object
['presence' => ['value' => true]]
```

```php
$client->subscribe("news", "user-42", "", 0, [], [], [], ["presence" => ["value" => true]]);
```

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

### Generate subscription token with 30-minute expiry

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Generate a channel subscription token that expires after 30 minutes. The expiration time is passed as the third argument.

```php
$token = $client->setSecret("Centrifugo secret key")->generateSubscriptionToken($userId, $channel, time() + 30*60);
```

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

### POST /api/batch

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Send a batch of API requests.

```APIDOC
## [POST] /api/batch

### Description
Send a batch of API requests.

### Method
POST

### Endpoint
/api/batch

### Parameters
#### Request Body
- **data** (array) - Required - Array of API requests

### Request Example
{
  "data": []
}

### Response
#### Success Response (200)
- **error** (object) - Error object
- **result** (object) - Result object

#### Response Example
{
  "error": null,
  "result": {}
}
```

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

### Use self-signed certificate safely

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Use a self-signed certificate in a safe manner by setting the certificate path and optionally the CA path. The certificate must match the host name in the Client address.

```php
$client = new \phpcent\Client("https://localhost:8000/api");
$client->setCert("/path/to/certificate.pem");
$client->setCAPath("/ca/path"); // if you need.
```

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

### phpcent\Client::setCert

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Sets the CA certificate path for SSL verification.

```APIDOC
## setCert

### Description
Sets the path to a CA certificate file for SSL verification.

### Signature
```php
public function setCert(string $cert): $this
```

### Parameters
- **$cert** (string) - Required - The path to the CA certificate file.

### Returns
Returns `$this` for fluent chaining.
```

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

### generateSubscriptionToken

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

Documentation for the subscription token payload generated by Client::generateSubscriptionToken().

```APIDOC
## generateSubscriptionToken

### Description
Generates a subscription token payload (JWT claims) for a given channel and user. The payload includes the channel, user ID, and optionally channel info and expiration time.

### Method
`generateSubscriptionToken`

### Parameters
- **channel** (string) - Required - The channel the token is generated for.
- **userId** (string) - Required - The user ID.
- **info** (array) - Optional - Channel info, included if non-empty.
- **exp** (int) - Optional - Expiration unix time, included if truthy.

### Request Example
```php
$payload = [
    'channel' => (string)$channel,
    'sub'     => (string)$userId,
    'info'    => $info,
    'exp'     => $exp,
];
```

### Response
Returns an array with the following claims:
- **channel** (string) - The channel the token is generated for.
- **sub** (string) - The user ID.
- **info** (array) - Channel info, if provided.
- **exp** (int) - Expiration unix time, if provided.
```

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

### generateConnectionToken

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-token-methods.md

Generates a connection JWT for a user. Builds the token locally using HS256 and returns it as a string. The payload includes the user ID in the `sub` claim, with optional `info`, `meta`, `channels`, and `exp` claims.

```APIDOC
## [METHOD] [ENDPOINT]

### Description
Generate a connection JWT for a user.

### Method
GENERATE_CONNECTION_TOKEN

### Endpoint
phpcent\Client::generateConnectionToken

### Parameters
#### Method Parameters
- **$userId** (string) - Required - Current user ID; cast to string with `(string) $userId` and placed in the `sub` claim. Since v5.0.0 this argument is not optional — pass `''` explicitly for anonymous users.
- **$exp** (int) - Optional - Default: `0` - Token expiration as future unix seconds; added as the `exp` claim only if truthy (non-zero). E.g. `time() + 5*60` for a 5-minute token
- **$info** (array) - Optional - Default: `array()` - User info; added as `info` claim if non-empty
- **$channels** (array) - Optional - Default: `array()` - Server-side channels to subscribe to; added as `channels` claim if non-empty
- **$meta** (array) - Optional - Default: `array()` - Meta data; added as `meta` claim if non-empty

### Return Value
- **string** — the signed JWT in `header.payload.signature` form (compact serialization, base64url without padding).

### Throws
- **\Exception** — none directly. If the secret is not set (empty), the token is still produced but signed with an empty key, which Centrifugo will reject unless the server secret is genuinely empty. No JSON encoding error is checked in this method.

### Source
`src/Client.php:405`

### Example
```php
$client = new 
phpcentClient("http://localhost:8000/api");
$token = $client->setSecret(
```

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

### POST {url}/channels

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Retrieves a list of channels matching a pattern.

```APIDOC
## POST {url}/channels

### Description
Retrieves a list of channels matching a pattern.

### Method
POST

### Endpoint
{url}/channels

### Parameters
#### Request Body
- **pattern** (string) - Required - The pattern to match channels. Default is an empty string.

### Request Example
{
  "pattern": "<pattern>"
}

```

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

### Generate subscription token

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Generate a channel subscription token for a user and channel. This token is used to authorize subscription to a specific channel.

```php
$token = $client->setSecret("Centrifugo secret key")->generateSubscriptionToken($userId, $channel);
```

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

### Tags map for publish() and broadcast()

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

Shape of the tags map for publish() and broadcast(). The map is sent as 'tags' only when non-empty.

```php
// Map of string key/value tags attached to the publication (associative array)
array $tags = ["lang" => "en"]
```

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

### POST {url}/presence

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Retrieves presence information for a channel.

```APIDOC
## POST {url}/presence

### Description
Retrieves presence information for a channel.

### Method
POST

### Endpoint
{url}/presence

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to query.

### Response
No response body documented.
```

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

### setCert

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Sets the path to a PEM CA certificate bundle, applied as CURLOPT_CAINFO when safety is enabled. Returns $this for fluent chaining.

```APIDOC
## setCert

### Description
Sets the path to a PEM CA certificate bundle, applied as `CURLOPT_CAINFO` when safety is enabled. Returns `$this` for fluent chaining.

### Method
setCert

### Endpoint
`Client::setCert($cert)`

### Parameters
#### Path Parameters
- `$cert` (string) - Required - Path to a PEM CA certificate bundle, applied as `CURLOPT_CAINFO` when safety is enabled

### Request Example
```php
$client = new \phpcent\Client("https://localhost:8000/api");
$client->setCert("/path/to/certificate.pem");
```

### Response
#### Success Response (200)
- **Return** (Client) - `$this`, for fluent chaining.

#### Response Example
```php
$client = new \phpcent\Client("https://localhost:8000/api");
$client->setCert("/path/to/certificate.pem");
```
```

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

### POST {url}/subscribe

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Subscribes a user or client to a channel.

```APIDOC
## POST {url}/subscribe

### Description
Subscribes a user or client to a channel.

### Method
POST

### Endpoint
{url}/subscribe

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to subscribe to.
- **user** (string) - Required - The user identifier.
- **client** (string) - Required - The client identifier (may be empty string).
- **expire_at** (int) - Optional - Expiration timestamp, included if truthy.
- **info** (object) - Optional - Additional info, included if not empty.
- **data** (object) - Optional - Additional data, included if not empty.
- **recover_since** (object with `offset` and `epoch`) - Optional - Recovery point, included if not empty.
- **override** (object mapping option to `{"value": ...}`) - Optional - Override options, included if not empty.
- **session** (string) - Optional - Session identifier, included if not empty string.

### Response
No response body documented.
```

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

### Set connection and request timeouts

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Set connection and request timeouts. The connection timeout of 0 means never time out; the request timeout is set to 2 seconds.

```php
$client->setConnectTimeoutOption(0); // Seconds | 0 = never
$client->setTimeoutOption(2); // Seconds
```

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

### phpcent\Client::setCAPath

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Sets the CA certificate directory path for SSL verification.

```APIDOC
## setCAPath

### Description
Sets the path to a directory containing CA certificates for SSL verification.

### Signature
```php
public function setCAPath(string $caPath): $this
```

### Parameters
- **$caPath** (string) - Required - The path to the CA certificate directory.

### Returns
Returns `$this` for fluent chaining.
```

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

### POST {url}/history

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Retrieves history for a channel.

```APIDOC
## POST {url}/history

### Description
Retrieves history for a channel.

### Method
POST

### Endpoint
{url}/history

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to query.
- **limit** (int) - Required - Maximum number of items to return (default 0).
- **reverse** (boolean) - Required - Whether to return in reverse order (default false).
- **since** (object with `offset` and `epoch`) - Optional - History since a specific point, included if not empty.

### Response
No response body documented.
```

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

### setSafety

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Configures TLS peer verification behavior for the client. When set to false, disables SSL certificate verification, useful for development environments with invalid certificates.

```APIDOC
## setSafety

### Description
Configures TLS peer verification behavior for the client. When set to false, disables SSL certificate verification, useful for development environments with invalid certificates.

### Method
setSafety

### Endpoint
setSafety($safety)

### Parameters
#### Path Parameters
- `$safety` (boolean) - Required - When `false`, TLS peer verification is disabled (`CURLOPT_SSL_VERIFYPEER = false`, `CURLOPT_SSL_VERIFYHOST = 0`). When `true` (default), the client sets `CURLOPT_SSL_VERIFYPEER = true` and `CURLOPT_SSL_VERIFYHOST = 2` and applies `CURLOPT_CAINFO`/`CURLOPT_CAPATH` if `setCert()`/`setCAPath()` were called.

### Request Example
```php
// Use this only if your Centrifugo server has an invalid TLS certificate.
$client->setSafety(false);
```

### Response
#### Success Response (200)
- **Return** (Client) - `$this`, for fluent chaining.

#### Response Example
```php
try {
    $client = new \phpcent\Client("https://localhost:8000/api");
    $client->setSafety(false);
    $client->publish("channel", ["message" => "Hello World"]);
} catch (\Exception $e) {
    // json_decode error, or non-200 HTTP response (see errors.md)
    error_log($e->getMessage());
}
```
```

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

### forceIpResolveV4 method and usage

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Forces DNS to resolve IPv4 addresses only by setting CURLOPT_IPRESOLVE = CURL_IPRESOLVE_V4 on every request. Useful against 'cURL error: Resolving timed out after ...' errors. Returns $this for fluent chaining.

```php
public function forceIpResolveV4()
```

```php
$client->forceIpResolveV4();
```

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

### broadcast

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Broadcast the same data into multiple channels. Parameter semantics are identical to publish() except $channels (array) is sent as channels; the base payload is channels, data, skip_history.

```APIDOC
## `broadcast`

### Description
Broadcast the same data into multiple channels. Parameter semantics are identical to `publish()` except `$channels` (array) is sent as `channels`; the base payload is `channels`, `data`, `skip_history`.

### Method
`broadcast`

### Signature
```php
public function broadcast($channels, $data, $skipHistory = false, $tags = array(), $idempotencyKey = '', $delta = false, $version = 0, $versionEpoch = '')
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$channels` | array | yes | — | List of channel names |
| `$data` | array | yes | — | Publication data |
| `$skipHistory` | boolean | no | `false` | Sent as `skip_history` |
| `$tags` | array | no | `array()` | Sent as `tags` if non-empty |
| `$idempotencyKey` | string | no | `''` | Sent as `idempotency_key` if not `''` |
| `$delta` | boolean | no | `false` | Sent as `delta` if truthy |
| `$version` | int | no | `0` | Sent as `version` if truthy |
| `$versionEpoch` | string | no | `''` | Sent as `version_epoch` if not `''` |

### Return
`mixed` — decoded JSON response.

### Throws
`\Exception` — as documented in errors.md.

### Source
`src/Client.php:185`

### Request Example
```php
$client->broadcast(["ch1", "ch2", "ch3"], ["message" => "Hello everyone"]);
```

```php
$client->broadcast(["ch1", "ch2"], ["message" => "Hello"], true, ["env" => "prod"]);
```
```

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

### POST {url}/publish

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Publishes a message to a single channel. The request body always includes `channel`, `data`, and `skip_history`; optional fields are included based on the conditions listed.

```APIDOC
## POST {url}/publish

### Description
Publishes a message to a single channel. The request body always includes `channel`, `data`, and `skip_history`; optional fields are included based on the conditions listed.

### Method
POST

### Endpoint
{url}/publish

### Parameters
#### Request Body
- **channel** (string) - Required - The channel name to publish to.
- **data** (array) - Required - The message payload.
- **skip_history** (boolean) - Required - Whether to skip history for this publish.
- **tags** (object/map) - Optional - Included when `!empty($tags)`.
- **idempotency_key** (string) - Optional - Included when `$idempotencyKey !== ''`.
- **delta** (boolean) - Optional - Included when `$delta` is truthy.
- **version** (int) - Optional - Included when `$version` is truthy.
- **version_epoch** (string) - Optional - Included when `$versionEpoch !== ''`.

### Request Example
{
  "channel": "string",
  "data": {},
  "skip_history": true,
  "tags": {},
  "idempotency_key": "string",
  "delta": true,
  "version": 0,
  "version_epoch": "string"
}

### Response
#### Success Response (200)
- **result** (object) - Empty object on success.

#### Response Example
{
  "result": {}
}

#### Error Response
- **error** (object) - Contains `code` and `message` on Centrifugo command error.

#### Error Example
{
  "error": {
    "code": 102,
    "message": "unknown channel"
  }
}
```

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

### POST {url}/presence_stats

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Retrieves presence statistics for a channel.

```APIDOC
## POST {url}/presence_stats

### Description
Retrieves presence statistics for a channel.

### Method
POST

### Endpoint
{url}/presence_stats

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to query.

### Response
No response body documented.
```

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

### Generate connection token

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Generate a connection token (JWT) using the client's secret key. The token is used for authenticating client connections.

```php
$token = $client->setSecret("Centrifugo secret key")->generateConnectionToken($userId);
```

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

### phpcent\Client::forceIpResolveV4

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Forces IPv4 resolution for cURL requests.

```APIDOC
## forceIpResolveV4

### Description
Forces cURL to resolve IP addresses to IPv4 only.

### Signature
```php
public function forceIpResolveV4(): $this
```

### Returns
Returns `$this` for fluent chaining.
```

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

### phpcent\Client::setApiKey

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Sets the API key for the client.

```APIDOC
## setApiKey

### Description
Sets the API key used for authentication with the Centrifugo server.

### Signature
```php
public function setApiKey(string $apikey): $this
```

### Parameters
- **$apikey** (string) - Required - The API key to set.

### Returns
Returns `$this` for fluent chaining.
```

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

### phpcent Client constructor signature

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/configuration.md

Constructor signature for phpcent\Client. The url is required; apikey and secret default to empty strings. The apikey is sent as the X-API-Key header on every request, and the secret is used for HMAC-SHA256 JWT generation.

```php
public function __construct($url, $apikey = '', $secret = '')
```

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

### SubscribeOptionOverride

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

Documentation for the SubscribeOptionOverride type, a server-side override of subscription options on subscribe.

```APIDOC
## SubscribeOptionOverride

### Description
Server-side override of subscription options on `subscribe`. Documented in `src/Client.php:228` as `SubscribeOptionOverride, e.g. ['presence' => ['value' => true]]`.

### Definition

```php
// PHPDoc shape (associative array); each key is an option name mapped to a {"value": ...} object
['presence' => ['value' => true]]
```

### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `presence` (and other Centrifugo subscription-option keys) | array | no | Override object of the form `['value' => <bool/int/string>]` |

### Usage

Sent as `override` by `Client::subscribe()` when non-empty (`src/Client.php:224`).

```php
$client->subscribe("news", "user-42", "", 0, [], [], [], ["presence" => ["value" => true]]);
```
```

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

### batch

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-api-methods.md

Sends many commands in one request to the Centrifugo server. The payload is passed through unchanged, with a top-level object cast applied.

```APIDOC
## batch

### Description
Send many commands in one request.

### Method
POST

### Endpoint
/batch

### Parameters
#### Request Body
- **$data** (array) - Required - Batch request payload, passed through unchanged; shape `["commands" => [["<method>" => ["<param>" => ...]], ...]]` per the Centrifugo batch API.

### Request Example
```php
$data = [
    "commands" => [
        ["presence_stats" => ["channel" => "test1"]],
        ["publish" => ["channel" => "x:test2", "data" => []]],
    ],
];
$res = $client->batch($data);
```

### Response
#### Success Response (200)
- **replies** (array) - Array of per-command replies.

#### Response Example
```json
{
  "replies": []
}
```

### Error Handling
- **Throws:** `\Exception` - As documented in errors.md.
```

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

### Force IPv4 resolution

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Force the client to resolve only IPv4 addresses. Useful when the system has trouble resolving IPv6 addresses.

```php
$client->forceIpResolveV4();
```

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

### generateConnectionToken method signature

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client-token-methods.md

Generates a connection JWT locally using HS256. The signing key is the secret from the constructor or setSecret(); an empty secret still produces a valid HMAC-SHA256 signature. Does not support all Centrifugo connection-token claims.

```php
public function generateConnectionToken($userId, $exp = 0, $info = array(), $channels = array(), $meta = array())
```

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

### POST {url}/unsubscribe

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/endpoints.md

Unsubscribes a user or client from a channel.

```APIDOC
## POST {url}/unsubscribe

### Description
Unsubscribes a user or client from a channel.

### Method
POST

### Endpoint
{url}/unsubscribe

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to unsubscribe from.
- **user** (string) - Required - The user identifier.
- **client** (string) - Required - The client identifier (may be empty string).
- **session** (string) - Optional - Session identifier, included if not empty string.

### Response
No response body documented.
```

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

### forceIpResolveV4

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/api-reference/client.md

Forces DNS to resolve IPv4 addresses only on every request.

```APIDOC
## `forceIpResolveV4`

```php
public function forceIpResolveV4()
```

### Description
Forces DNS to resolve IPv4 addresses only by setting `CURLOPT_IPRESOLVE = CURL_IPRESOLVE_V4` on every request. Useful against "cURL error: Resolving timed out after ..." errors on systems where IPv6 resolution hangs.

### Method
`forceIpResolveV4`

### Parameters
None.

### Return
`Client` — `$this`, for fluent chaining.

### Example
```php
$client->forceIpResolveV4();
```
```

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

### Connection token payload (JWT claims) for generateConnectionToken()

Source: https://github.com/centrifugal/phpcent/blob/master/_autodocs/types.md

Claims payload assembled inside generateConnectionToken(). The 'sub' claim is always present; other claims are added conditionally.

```php
$payload = [
    'sub'      => (string)$userId,   // always
    'info'     => $info,             // only if !empty($info)
    'meta'     => $meta,             // only if !empty($meta)
    'channels' => $channels,         // only if !empty($channels)
    'exp'      => $exp,              // only if truthy
];
```

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

### Set assoc option for JSON decoding

Source: https://github.com/centrifugal/phpcent/blob/master/README.md

Enable the 'assoc' option to decode JSON responses as associative arrays instead of objects.

```php
$client->setUseAssoc(true);
```
Tokens:
Raw