Skip to content
PAM

pushinbr/pam-socket

pushinbr/pam-socket adds an event-oriented PHP API above PAM’s native WebSocket transport.

Start here

Section titled “Start here”

Install and verify the PAM runtime first, create an HTTP application, and add the Socket package through PAM’s Composer passthrough:

Terminal window
curl -fsSL https://github.com/push-in/pam/releases/latest/download/install.sh | sh
pam doctor
pam init my-api --template http
cd my-api
pam composer require pushinbr/pam-socket

Create a server

Section titled “Create a server”
use Pam\Socket\Server;


$io = Server::create();


$io->auth(static function ($handshake) {
    // Validate credentials before connection handlers run.
    return $handshake->header('authorization') !== null;
});


$io->on('connection', static function ($socket): void {
    $socket->emit('ready', ['connected' => true]);
});

The package checks the runtime ABI and requires the native WebSocket capability during construction. It fails immediately when loaded outside a compatible PAM runtime.

Events

Section titled “Events”

Register handlers with on() and send events with emit():

$io->on('message.send', static function ($socket, array $payload): void {
    $socket->to('room:'.$payload['roomId'])->emit('message.created', [
        'id' => $payload['id'],
        'body' => $payload['body'],
    ]);
});

Validate and authorize payloads inside the domain boundary. Event names and values cross the network and must be treated as public input.

Rooms

Section titled “Rooms”

Target a room through to():

$io->to('project:42')->emit('project.updated', [
    'projectId' => 42,
]);

In-memory rooms belong to a worker. Configure an adapter when several workers or nodes must share broadcasts.

Adapters

Section titled “Adapters”

The native WebSocket surface supports distributed adapters including Redis Streams and NATS. An adapter coordinates live events; it does not replace durable domain storage.

Protocol limitation

Section titled “Protocol limitation”

PAM speaks RFC 6455 WebSockets. It is not compatible with the Engine.IO or Socket.IO wire protocols. Use a standards-based WebSocket client or implement a separate compatibility gateway.

Delivery semantics

Section titled “Delivery semantics”

Rooms, emits, acknowledgements, and resume tokens help realtime applications, but they do not create exactly-once delivery.

For critical actions:

  • assign a stable domain event or command ID;
  • make handlers idempotent;
  • persist state before acknowledging success;
  • store replayable events when offline recovery matters; and
  • reconnect after worker generation changes.

Security

Section titled “Security”
  • Authenticate before privileged handlers or room membership.
  • Authorize every resource referenced by a payload.
  • Limit message size, connection count, and event rate.
  • Keep internal exception details out of client events.
  • Configure a resume secret of at least 32 bytes through a secret manager.

Complete PHP surface

Section titled “Complete PHP surface”

Pam\Socket\Server is the package’s public facade:

Method Result
Server::create() Wrap the PAM native WebSocket server after ABI/capability validation
adapter(Adapter $adapter) Select the cross-worker broadcast adapter; fluent Server
on(string $event, callable $handler) Register an event handler; fluent Server
auth(callable $authenticator) Register handshake authentication; fluent Server
emit(string $event, mixed $data = null) Broadcast through the native server; fluent Server
to(string $room) Return a native RoomEmitter scoped to one room

The public $server property exposes the underlying Pam\Native\WebSocket\Server for native operations not re-exposed by the facade. Code using that escape hatch is coupled to the runtime package and should pin/test its ABI.