README

Official PHP server SDK for Sockudo — a fast, self-hosted WebSocket server with full Pusher HTTP API compatibility.

Supported Platforms

PHP — 8.0, 8.1, 8.2, 8.3, 8.4
Laravel — 8.29 and above (built-in Broadcasting driver support)
Other PHP frameworks are supported provided you are running a supported PHP version.

Installation

composer require sockudo/sockudo-php-server:^2.0

Packagist reads this package from the read-only sockudo/sockudo-http-php mirror. Development happens in the Sockudo monorepo under server-sdks/sockudo-http-php.

For local monorepo development, add a path repository to composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../sockudo/server-sdks/sockudo-http-php"
        }
    ],
    "require": {
        "sockudo/sockudo-php-server": "*"
    }
}

Then run composer update sockudo/sockudo-php-server.

Constructor

use Sockudo\Sockudo;

$sockudo = new Sockudo([
    'app_id'  => 'your-app-id',
    'key'     => 'your-app-key',
    'secret'  => 'your-app-secret',
    'host'    => '127.0.0.1',
    'port'    => 6001,
    'useTLS'  => false,
]);

Options

Option	Type	Default	Description
`app_id`	string	—	Application ID
`key`	string	—	Application key
`secret`	string	—	Application secret
`host`	string	`127.0.0.1`	Sockudo server host
`port`	int	`6001`	Sockudo server port
`useTLS`	bool	`false`	Use HTTPS
`scheme`	string	`http`	URL scheme (`http` or `https`)
`timeout`	int	`30`	HTTP request timeout in seconds
`path`	string	—	Optional path prefix for all requests

Publishing Events

Single Channel

$sockudo->trigger('my-channel', 'my-event', ['message' => 'hello world']);

Multiple Channels

$sockudo->trigger(['channel-1', 'channel-2'], 'my-event', ['message' => 'hello world']);

Excluding a Socket Recipient

Pass socket_id in the options array to prevent the sender from receiving its own event:

$sockudo->trigger('my-channel', 'my-event', ['message' => 'hello'], ['socket_id' => $socket_id]);

Batch Events

Send multiple events in a single HTTP request (up to 10 events per call):

$batch = [
    ['channel' => 'channel-1', 'name' => 'event-1', 'data' => ['x' => 1]],
    ['channel' => 'channel-2', 'name' => 'event-2', 'data' => ['x' => 2]],
    ['channel' => 'channel-3', 'name' => 'event-3', 'data' => ['x' => 3]],
];

$sockudo->triggerBatch($batch);

Asynchronous Publishing

Both trigger and triggerBatch have async counterparts that return Guzzle promises:

$promise = $sockudo->triggerAsync(['channel-1', 'channel-2'], 'my-event', ['message' => 'hello']);

$promise->then(function ($result) {
    // handle result
});

$final = $promise->wait();

Idempotent Publishing

Pass an idempotency_key to safely retry publishes without causing duplicate deliveries:

$sockudo->trigger('my-channel', 'my-event', ['message' => 'hello'], [
    'idempotency_key' => 'order-shipped-order-789',
]);

The server deduplicates publishes with the same key within the configured window.

Channel Authorization

Private Channel

$auth = $sockudo->authorizeChannel('private-my-channel', $socket_id);
echo $auth; // JSON: {"auth":"key:signature"}

Presence Channel

$auth = $sockudo->authorizePresenceChannel(
    'presence-my-channel',
    $socket_id,
    $user_id,
    ['name' => 'Jane Doe', 'role' => 'admin']
);
echo $auth; // JSON: {"auth":"key:signature","channel_data":"..."}

User Authentication

$auth = $sockudo->authenticateUser($socket_id, $user_id);
echo $auth;

Webhooks

Pass the raw request headers and body to verify and parse incoming webhooks:

$webhook = $sockudo->webhook($request_headers, $request_body);

$events = $webhook->get_events();
$time_ms = $webhook->get_time_ms();

foreach ($events as $event) {
    echo $event->name . ' on ' . $event->channel . PHP_EOL;
}

An exception is thrown if the signature cannot be validated.

Application State Queries

// Get info about a specific channel
$info = $sockudo->getChannelInfo('my-channel');
$occupied = $info->occupied;

// Get user count for a presence channel
$info = $sockudo->getChannelInfo('presence-my-channel', ['info' => 'user_count']);
$user_count = $info->user_count;

// List all channels
$result = $sockudo->getChannels();

// Filter channels by prefix
$result = $sockudo->getChannels(['filter_by_prefix' => 'presence-']);

// Get users in a presence channel
$result = $sockudo->getPresenceUsers('presence-my-channel');

Laravel Integration

Laravel 8.29+ has built-in support for the Pusher Channels HTTP API as a Broadcasting backend. Since Sockudo is fully API-compatible, configure it in config/broadcasting.php:

'pusher' => [
    'driver' => 'pusher',
    'key'    => env('SOCKUDO_APP_KEY'),
    'secret' => env('SOCKUDO_APP_SECRET'),
    'app_id' => env('SOCKUDO_APP_ID'),
    'options' => [
        'host'   => env('SOCKUDO_HOST', '127.0.0.1'),
        'port'   => env('SOCKUDO_PORT', 6001),
        'scheme' => 'http',
        'useTLS' => false,
    ],
],

PSR-3 Logger Support

The Sockudo class implements Psr\Log\LoggerAwareInterface. Assign any PSR-3 compatible logger:

// e.g. Monolog, Laravel's Log facade, etc.
$sockudo->setLogger($logger);

Custom Guzzle Client

Pass your own Guzzle instance to customise HTTP behaviour (middleware, retry logic, etc.):

$guzzle = new GuzzleHttp\Client([
    'timeout' => 5.0,
]);

$sockudo = new Sockudo(
    ['app_id' => '...', 'key' => '...', 'secret' => '...'],
    $guzzle
);

Running the Tests

composer install
composer exec phpunit

Channel History

$page = $sockudo->getChannelHistory('my-channel', [
    'limit' => 50,
    'direction' => 'newest_first',
]);

$nextPage = $sockudo->getChannelHistory('my-channel', [
    'cursor' => 'opaque-cursor-from-previous-page',
]);

Pusher SDK Compatibility

Sockudo implements the full Pusher HTTP API. If you prefer to use the official pusher/pusher-php-server package or are migrating from Pusher, point it at your Sockudo instance:

$pusher = new Pusher\Pusher($key, $secret, $app_id, [
    'host'   => '127.0.0.1',
    'port'   => 6001,
    'scheme' => 'http',
]);

All standard Pusher SDK calls work against a self-hosted Sockudo server without modification.

License

MIT

sockudo / sockudo-php-server

Maintainers

Package info

Statistics

Security