README

Framework-agnostic PHP transport for the RelayStacks Conduit broadcasting ecosystem.

Serializes broadcast messages as newline-delimited JSON, optionally signs them with HMAC-SHA256, and writes them to a Unix domain socket. The receiving end is the @relaystacks/conduit-echo Node.js relay server.

Zero framework dependencies — requires only PHP 8.1+.

Installation

composer require relaystacks/conduit-php

Quick Start

use RelayStacks\Conduit\UnixSocketTransport;

$transport = new UnixSocketTransport(
    socketPath: '/home/user/laravel.sock',
    secret: 'your-shared-secret', // optional
);

$success = $transport->send('chat-room', 'NewMessage', [
    'user' => 'Alice',
    'text' => 'Hello!',
]);

API Reference

TransportInterface

The contract for all Conduit transports.

public function send(string $channel, string $event, array $data = []): bool;

UnixSocketTransport

The default (and only) transport implementation. Sends JSON frames over a Unix domain socket.

Constructor

Methods

• send(string $channel, string $event, array $data = []): bool — Serialize and write the message. Returns true if the full frame was written.

ConduitException

Domain exception extending RuntimeException. Available for consumers to catch Conduit-specific errors.

HMAC Signing

When a $secret is provided, each message is signed with HMAC-SHA256:

1. The body {channel, event, data} is JSON-encoded
2. The HMAC is computed over that JSON string: hash_hmac('sha256', $json, $secret)
3. The hmac field is appended to the body
4. The complete body (with HMAC) is JSON-encoded again as the final frame

The verifier (conduit-echo) must strip the hmac field and re-encode the remaining body to reproduce the signature. This works because both PHP's json_encode and JavaScript's JSON.stringify produce deterministic key ordering for simple objects.

Wire Format

Each frame is a single line of JSON terminated by \n.

Unsigned:

{"channel":"chat-room","event":"NewMessage","data":{"user":"Alice","text":"Hello!"}}

Signed:

{"channel":"chat-room","event":"NewMessage","data":{"user":"Alice","text":"Hello!"},"hmac":"a1b2c3..."}

Use Without Laravel

This package works with any PHP framework or plain PHP scripts. For Laravel integration (broadcast driver, channel authorization, service provider), see relaystacks/laravel-conduit.

Requirements

• PHP >= 8.1
• Unix-like OS (Unix domain sockets are not available on Windows)

License

MIT