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(
    'your-app-key',
    'your-app-secret',
    'your-app-id',
    [
        '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;

Force Reconnect User

Close all active connections for a user with code 4200, prompting clients to reconnect:

// Synchronous
$sockudo->forceReconnectUser("user-123");

// Asynchronous
$promise = $sockudo->forceReconnectUserAsync("user-123");
$promise->wait();

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-key',
    'app-secret',
    'app-id',
    ['host' => '127.0.0.1', 'port' => 6001, 'useTLS' => false],
    $guzzle,
);

Apple Live Activities

Use publishPush() for direct-token and broadcast ActivityKit notifications. Manage iOS 18 APNs broadcast channels with createApnsLiveActivityChannel(), getApnsLiveActivityChannel(), listApnsLiveActivityChannels(), and deleteApnsLiveActivityChannel(). Reuse publishId for safe retries. See the Apple Live Activities guide.

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

Package info

Security

Statistics