README

Shared data model, serialization, middleware pipeline, and contract system for RPC over WebSocket.

This is the foundation library — both rpc-client and rpc-server depend on it.

Install

composer require php-websocket-rpc/rpc

Requires PHP 8.5+ and the msgpack extension.

Features

Payload model — base class and kind interfaces (request, response, notification, stream open/close/data)
Contract system — ContractInvocation, ContractResponse, ContractStreamInvocation, ContractStreamValue, ContractStreamClose, ContractPublish
PHP Attributes — #[RpcSubscribe], #[RpcStream], #[RpcPublish], #[NeedAuthorization] for declaring RPC patterns on interfaces
Serialization — ContractSerializer encodes/decodes values for wire transmission using [FQCN, props] format
Middleware pipeline — MiddlewarePipeline for chaining request/response processors
Stream interfaces — StreamChannelAware, StreamSubscribable for streaming and pub/sub
Authentication — AuthService contract, WebsocketUserInterface, User value object, typed auth exceptions

Contract Attributes

Attribute	Target	Purpose
`#[RpcSubscribe]`	Method	Subscribe to a named channel (receives push data)
`#[RpcStream]`	Method	Stream data as an async iterable
`#[RpcPublish]`	Method	Publish data to a named channel
`#[NeedAuthorization]`	Method/Class	Require authentication to access a method or entire interface

Authentication

AuthService Contract

A built-in contract that all clients can use to authenticate:

use PhpWebsocketRpc\Rpc\Contract\AuthService;

$auth = $client->createProxy(AuthService::class);
$user = $auth->authenticate('jwt-token-here');
// $user instanceof PhpWebsocketRpc\Rpc\Auth\User
// $user->id, $user->roles

WebsocketUserInterface

interface WebsocketUserInterface
{
    public function getUniqueIdentifier(): string;
    public function getRoles(): array;
}

User (built-in value object)

$user = new User('user-42', ['admin', 'customer']);
echo $user->id;          // 'user-42'
echo $user->roles;       // ['admin', 'customer']

Error Codes

Exception	Code	Meaning
`AuthenticationException`	-32010	Invalid/expired/missing token
`AuthorizationException`	-32011	Insufficient permissions

Both extend RpcDispatchException and carry the error code in getRpcCode().

Key Classes

Class	Purpose
`PhpWebsocketRpc\Rpc\Payload\Payload`	Base class for all wire payloads
`PhpWebsocketRpc\Rpc\Serialization\Serializer`	Msgpack serialization
`PhpWebsocketRpc\Rpc\Contract\ContractSerializer`	Object encoding/decoding for contract data
`PhpWebsocketRpc\Rpc\Contract\Attribute\RpcSubscribe`	Mark a method as subscribe pattern
`PhpWebsocketRpc\Rpc\Contract\Attribute\RpcStream`	Mark a method as stream pattern
`PhpWebsocketRpc\Rpc\Contract\Attribute\RpcPublish`	Mark a method as publish pattern
`PhpWebsocketRpc\Rpc\Contract\Attribute\NeedAuthorization`	Mark a method/interface as requiring auth
`PhpWebsocketRpc\Rpc\Contract\AuthService`	Built-in authentication contract
`PhpWebsocketRpc\Rpc\Auth\WebsocketUserInterface`	Interface for authenticated user data
`PhpWebsocketRpc\Rpc\Auth\User`	Value object implementing WebsocketUserInterface
`PhpWebsocketRpc\Rpc\Exception\AuthenticationException`	Auth failure (-32010)
`PhpWebsocketRpc\Rpc\Exception\AuthorizationException`	Forbidden (-32011)
`PhpWebsocketRpc\Rpc\Middleware\MiddlewarePipeline`	Middleware chain

php-websocket-rpc / rpc

Maintainers

Package info

Statistics

Security