PHPackages                             monkeyscloud/monkeyslegion-sockets - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. monkeyscloud/monkeyslegion-sockets

ActiveLibrary[HTTP & Networking](/categories/http)

monkeyscloud/monkeyslegion-sockets
==================================

High-performance, secure, and cluster-ready WebSocket architecture for the MonkeysLegion ecosystem. Features active liveness monitoring, distributed state management, and multi-driver support (Native, ReactPHP, Swoole).

1.1.2(1mo ago)0147↓77.8%1MITPHPPHP >=8.4CI failing

Since Apr 22Pushed 1mo agoCompare

[ Source](https://github.com/MonkeysCloud/MonkeysLegion-Sockets)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-sockets)[ RSS](/packages/monkeyscloud-monkeyslegion-sockets/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (11)Versions (7)Used By (1)

🐒 MonkeysLegion Sockets
=======================

[](#-monkeyslegion-sockets)

High-performance, secure, and cluster-ready WebSocket architecture for the MonkeysLegion framework. Designed for massive scalability, distributed state, and adversarial resilience.

🚀 Quick Setup
-------------

[](#-quick-setup)

Install the package and publish the configuration:

```
composer require monkeyscloud/monkeyslegion-sockets

# Interactive installer for config and JS client assets
php ml socket:install
```

### Starting the Cluster

[](#starting-the-cluster)

```
# Start the production server
php ml socket:serve start

# Or specify host/port
php ml socket:serve start --host=0.0.0.0 --port=9000
```

🛠️ Usage Examples
-----------------

[](#️-usage-examples)

### Server-Side Broadcasting

[](#server-side-broadcasting)

Target dynamic user streams or rooms with ease:

```
// Broadcast to a specific user on all connected devices
$broadcaster->channel('User.{id}', ['id' => 42])->emit('message', [
    'text' => 'Hello Monkey!'
]);

// Broadcast to a room
$broadcaster->to('room:lobby')->emit('message', 'Hello Monkeys!');
```

### Event Handling

[](#event-handling)

Define your socket events in your service providers or controllers:

```
$server->on('message', function($connection, $message) {
    echo "Received: " . $message->getPayload();
});
```

📚 Documentation
---------------

[](#-documentation)

For exhaustive, professional documentation covering every layer of the architecture, please see the `docs/` folder:

- [Handshake Security](docs/01-handshake.md)
- [Frame Processing](docs/02-frames.md)
- [Connection Registry](docs/03-connections.md)
- [Broadcasting Layer](docs/04-broadcasting.md)
- [Transport Drivers](docs/05-drivers.md)
- [Channels & Authorization](docs/06-channels.md)
- [Protocol & Serialization](docs/07-protocol.md)
- [Services](docs/08-services.md)
- [WebSocket Server](docs/09-server.md)
- [Configuration & CLI](docs/10-configuration.md)
- [Real-World Project Scenario](docs/11-real-world-example.md)

🏗️ Architectural Overview
-------------------------

[](#️-architectural-overview)

MonkeysLegion Sockets is a "Pure Consumer" DI-oriented library that decouples the transport layer (TCP/WebSockets) from the application logic.

### Core Components

[](#core-components)

- **Broadcaster**: Handles signal distribution from the application to the WebSocket workers (via Redis Pub/Sub or Unix Socket IPC).
- **Registry**: Manages distributed connection state (Tags, Rooms, Occupants). Supports Redis-backed clusters for multi-node deployments.
- **Drivers**: Transport implementations (Native Stream, ReactPHP, Swoole).
- **Middleware**: Handshake-level filtering (Authentication, Origin Check, Rate Limiting).

📊 Choosing the Right Driver
---------------------------

[](#-choosing-the-right-driver)

Selecting the right engine depends on your concurrency needs:

DriverBest ForProsCons**Native**Dev / Small AppZero dependencies, Pure PHPBlocking loop (High CPU)**React**High ConcurrencyAsynchronous, Pure PHPHigher Memory**Swoole**50k+ ConnectionsC-Extension Performance, Lowest FootprintRequires Swoole Ext🏠 Public and Private Channels
-----------------------------

[](#-public-and-private-channels)

MonkeysLegion Sockets provides a first-class, semantically clear system for managing communication groups.

### 🌍 Public Channels

[](#-public-channels)

Public channels are open to any connected client. Use them for global notifications, lobby chats, or public feeds.

```
// Server: Join a client to a public channel
$server->joinPublic($connection, 'lobby');

// Broadcast to a public channel
$broadcaster->publicChannel('lobby')->emit('announcement', 'Welcome!');
```

### 🔒 Private Channels

[](#-private-channels)

Private channels require server-side authorization. Use them for sensitive data, one-to-one messaging, or restricted groups.

```
// Server: Join with authorization logic (Requires ChannelAuthorizerInterface)
$server->joinPrivate($connection, 'team-alpha', ['token' => '...']);

// Broadcast to a private channel
$broadcaster->privateChannel('team-alpha')->emit('covert_op', 'Go!');
```

### 👥 Presence Channels

[](#-presence-channels)

A specialized type of private channel that tracks "Who's Online".

```
// Server: Join and get current occupants
$members = $server->joinPresence($connection, 'status-room');

// 1. Automatically emits 'presence:joined' to existing members
// 2. Returns an array of current members to the joiner
```

For more details on implementing security rules, see the [Rooms and Channels Architecture](ROOMS_AND_CHANNELS.md) guide.

🔒 Security Hardening
--------------------

[](#-security-hardening)

- **Strict Liveness (Heartbeats)**: Proactive Ping/Pong cycles ensure the server reaps zombie clients and bypasses protocol-level tricks.
- **Backpressure Protection**: Configurable `write_buffer_size` prevents memory exhaustion attacks.
- **Protocol Integrity**: Rigid RFC 6455 enforcement; only valid WebSocket frames reset liveness timers.
- **CSWH Protection**: Built-in `AllowedOriginsMiddleware`.

🏗️ Full Configuration Reference
-------------------------------

[](#️-full-configuration-reference)

The `config/sockets.mlc` file controls every aspect of your cluster. Below is the complete schema with default values:

```
sockets {
    # Transport driver: "stream", "swoole", or "react"
    driver ${WS_DRIVER:-stream},

    # State tracking: "local" or "redis"
    registry ${WS_REGISTRY:-local},

    # Pub/Sub strategy: "unix" (single-server) or "redis" (cluster)
    broadcast ${WS_BROADCAST:-redis},

    # Protocol Formatter: "json" or "msgpack"
    formatter ${WS_FORMATTER:-json},

    # Listening address and port
    host ${WS_HOST:-0.0.0.0},
    port ${WS_PORT:-8080},

    # Unix Socket path (required if broadcast is "unix")
    unix {
        path ${WS_UNIX_PATH:-/tmp/ml_sockets.sock},
    }

    # Low-level transport options
    options {
        # Maximum allowed WebSocket message size (Default: 10MB)
        max_message_size ${WS_MAX_MESSAGE_SIZE:-10485760},

        # Max outbound buffer per connection (Default: 5MB)
        write_buffer_size ${WS_WRITE_BUFFER_SIZE:-5242880},

        # Interval for active WebSocket Pings (Seconds)
        heartbeat_interval ${WS_HEARTBEAT_INTERVAL:-60},
    }

    # Handshake security
    security {
        # List of allowed domains for WebSocket handshakes (CSWH Protection)
        allowed_origins [
            "http://localhost:3000",
            "https://app.yoursite.com"
        ],
    }
}

```

---

📡 Communication Life-Cycles
---------------------------

[](#-communication-life-cycles)

To master the MonkeysLegion ecosystem, it is essential to understand the "Hub and Spoke" model. The architecture distinguishes between **Long-Lived** listeners and **Short-Lived** emitters to ensure maximum performance.

### 1. Server-to-Server (The Internal Bridge)

[](#1-server-to-server-the-internal-bridge)

This flow connects your application logic (e.g., a Controller, Command, or Job) to the WebSocket cluster.

- **The Listener (Always Live):** When you run `php ml socket:serve`, the server starts a permanent loop. It keeps an "Eternal Ear" open to the **Redis Pub/Sub** or **Unix Socket** channel.
- **The Broadcaster (Flash Messenger):** When your app calls `$broadcaster->emit()`, it "lives" for a few milliseconds—just long enough to throw the message into the channel—and then "dies" immediately.
- **Benefit:** Your web request is never slowed down by the WebSocket delivery process. It's a "fire and forget" system.

### 2. Client-to-Server (The Upstream Flow)

[](#2-client-to-server-the-upstream-flow)

Standard communication from the JS client to your backend logic.

- **The Flow:** The `MonkeysSocket` JS client initiates a handshake and remains "Live" in the browser. When it emits an event, the server's **Middleware** validates the request and triggers your defined event handlers.
- **Liveness:** Every message sent by the client resets the server-side "Heartbeat" timer, proving the connection is still active.

### 3. Client-to-Client (The Secure Relay)

[](#3-client-to-client-the-secure-relay)

Clients never talk directly to each other (P2P). Instead, the server acts as a secure **Mediator**.

- **The Process:** Client A emits to the server. The server verifies the permissions, looks up Client B in the **Registry**, and "relays" the message.
- **Echo Logic:** By default, the server broadcasts to "Everyone Else" (excluding the sender). This prevents "double-message" glitches in the sender's UI while ensuring the rest of the room is updated instantly.

---

### 📊 Summary Table

[](#-summary-table)

Flow TypeListener (Always Live)Emitter (Lives & Dies)Purpose**Server-to-Server**Socket Server (Worker)App BroadcasterPushing logic updates to users**Client-to-Server**Socket Server (Worker)JS ClientSending user actions to backend**Client-to-Client**Other Connected ClientsThe Sending ClientPrivate messaging / Chat rooms🏗️ Real-World Implementation Guide
----------------------------------

[](#️-real-world-implementation-guide)

Understanding which component to use and where to place your logic is key to a robust implementation.

### 🌲 The Architectural Tree

[](#-the-architectural-tree)

This map shows the hierarchy of responsibility within the system:

```
WebSocketServer (The Orchestrator)
├── Handshake (Middleware Pipeline)
│   └── Rejects unauthorized HTTP requests before they become WebSockets.
├── Registry (State Manager)
│   └── Tracks who is online and what tags they have.
├── RoomManager (High-Level Logic)
│   ├── Public (Open rooms)
│   ├── Private (Authorized channels)
│   └── Presence (Real-time occupant tracking)
└── Broadcaster (Distribution Bridge)
    ├── Local (Internal delivery to local workers)
    └── Global (Distributed delivery via Redis/Unix)

```

### 🚀 Full Implementation Scenario: Secure Team Chat

[](#-full-implementation-scenario-secure-team-chat)

#### 1. Define Authorization (The Policy)

[](#1-define-authorization-the-policy)

Create a class that implements `ChannelAuthorizerInterface` to protect your channels.

```
class ChatAuthorizer implements ChannelAuthorizerInterface
{
    public function authorize(ConnectionInterface $connection, string $channel, array $params = []): bool
    {
        $userId = $connection->getMetadata()['user_id'] ?? null;

        // Example: Only members of Team 5 can join 'team-5'
        if (str_starts_with($channel, 'team-')) {
            $teamId = (int) substr($channel, 5);
            return $this->db->isMember($userId, $teamId);
        }

        return true; // Allow other channels
    }
}
```

#### 💡 Advanced: Authorization Pipelines

[](#-advanced-authorization-pipelines)

For complex applications, you can decouple your rules into a **Pipeline**. This allows you to split logic (e.g. Rate Limiting vs Database checks) into separate, reusable classes.

```
$pipeline = new AuthorizerPipeline();
$pipeline->addAuthorizer(new IpBlockerAuthorizer(), 100); // Check IP first (High priority)
$pipeline->addAuthorizer(new DatabaseAuthorizer(), 10);    // Check DB second

$server = new WebSocketServer($registry, $broadcaster, $formatter, $pipeline);
```

#### 2. Bootstrap the Server

[](#2-bootstrap-the-server)

In your Service Provider or entry point, wire up the components.

```
$server = new WebSocketServer(
    $registry,
    $broadcaster,
    $formatter,
    new ChatAuthorizer() // Inject your policy
);

// Attach event logic
$server->on('message', function($connection, $data) use ($server) {
    if ($data['event'] === 'join_team') {
        $server->joinPrivate($connection, "team-{$data['team_id']}");
    }
});
```

#### 3. Emitting from your Application

[](#3-emitting-from-your-application)

Anywhere in your app (Controllers, Jobs, Commands), use the **Broadcaster** to push updates.

```
// In a Controller after a database update
$broadcaster->privateChannel('team-5')->emit('task_updated', [
    'task_id' => 123,
    'status' => 'completed'
]);
```

---

🏗️ Developer Notes & Standards
----------------------------------

[](#️-developer-notes--standards)

### MonkeysLegion v2 Standards

[](#monkeyslegion-v2-standards)

This project strictly adheres to the [MonkeysLegion PHP 8.4 Code Standards](CODE_STANDARDS.md), including:

- **Attribute-First Configuration**: Metadata driven by native PHP 8.4 attributes.
- **Type-Safe Everything**: Mandatory strict types and PHPStan Level 9 compliance.
- **Asymmetric Visibility**: Using modern property hooks and refined visibility.
- **PSR Compliance**: Adherence to PSR-1, 4, 7, 11, 12, and 15.

To contribute or work on the library, ensure you have the `pcntl` and `posix` extensions for integration testing.

---

*Built with ❤️ by the MonkeysLegion Team (Advanced Agentic Coding).*

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance91

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

5

Last Release

43d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2913369?v=4)[Jorge Peraza](/maintainers/yorchperaza)[@yorchperaza](https://github.com/yorchperaza)

---

Top Contributors

[![Amanar-Marouane](https://avatars.githubusercontent.com/u/155680356?v=4)](https://github.com/Amanar-Marouane "Amanar-Marouane (25 commits)")[![yorchperaza](https://avatars.githubusercontent.com/u/2913369?v=4)](https://github.com/yorchperaza "yorchperaza (1 commits)")

---

Tags

phpsocketsreactphpreal-timeWebSocketsswooleclusteringBroadcastmonkeyslegionmonkeyscloud

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/monkeyscloud-monkeyslegion-sockets/health.svg)

```
[![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-sockets/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-sockets)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[symfony/symfony

The Symfony PHP framework

31.4k86.9M2.2k](/packages/symfony-symfony)[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B3.7k](/packages/guzzlehttp-psr7)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[hyperf/hyperf

A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease.

6.8k3.2k2](/packages/hyperf-hyperf)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)