Download the PHP package micilini/php-websockets without Composer

PHPSockets

Native PHP WebSocket and realtime chat foundation built from scratch with PHP sockets. Works standalone with plain PHP or inside Laravel applications.

Pure PHP WebSockets. Realtime chat. Private rooms. Bots. Laravel-ready.

Application Images

Overview

PHPSockets started in 2016 as an educational experiment demonstrating how to build a WebSocket server directly with PHP sockets, without Node.js, without socket.io, and without a third-party realtime runtime.

The project has now been rebuilt as a modern Composer package for PHP 8.2+, with a clean architecture, WebSocket protocol primitives, a realtime server runtime, a chat kit, private conversations, private group rooms, small attachments, emoji-safe payloads, bot hooks, optional storage adapters, and Laravel integration.

The goal is not only to provide a chat example.

The goal is to provide a native PHP realtime foundation that developers can use to build:

• realtime chat widgets;
• support chat systems;
• private rooms;
• collaborative dashboards;
• notification servers;
• internal realtime tools;
• chatbot-ready messaging flows;
• Laravel-powered realtime applications.

Features

• Native WebSocket core — handshake, frames, opcodes, close codes, ping/pong and payload validation.
• Pure PHP socket runtime — no socket.io, Ratchet, ReactPHP, Swoole, Workerman or Node.js required.
• Realtime server layer — connection registry, lifecycle events, message dispatching and safe closing.
• Chat Kit — sessions, unique display names, presence, global messages, direct messages and rooms.
• EasyChat example — simple global chat for beginners.
• MediumChat example — callback/event-driven chat for customization.
• PrivateChat example — global room, direct 1:1 conversations, private group rooms and unread badges.
• Private group rooms — create a room with selected online users only.
• Typing indicators — user feedback for active conversations.
• Message receipts — simple sent/received/read states in examples.
• Emoji support — safe UTF-8 text payloads with a built-in emoji picker in examples.
• Small attachments — images, PDFs and text files up to the configured limit.
• Downloadable file messages — delivered attachments include a download action.
• Fragmented text frame support — large JSON text messages can be reassembled safely.
• Storage adapters — in-memory, file JSONL messages and PDO-based SQL storage.
• Database migrations — SQLite, MySQL and PostgreSQL schemas through the migration runner.
• Bot hooks — register lightweight bots that can respond in global, direct and private group contexts.
• Laravel integration — Service Provider, Facade, publishable config and Artisan commands.
• Quality tooling — PHPUnit, PHPStan, PHP CS Fixer and GitHub Actions.
• Legacy preserved — the original 2016 EasyChat and MediumChat implementations are kept for historical reference.

Installation

Install through Composer:

For local development:

Requirements

Required:

• PHP 8.2 or higher;
• ext-sockets;
• ext-json;
• Composer.

Optional:

• ext-pdo for SQL storage adapters;
• ext-pdo_sqlite for SQLite storage and tests;
• Laravel 10, 11, 12 or 13 for Laravel integration.

Quick Start

Standalone PHP server

Create a simple WebSocket chat server:

Run it:

The WebSocket server will listen on:

Running the Examples

The example servers can be executed both from a cloned repository and from a project where the package was installed through Composer. The examples use examples/bootstrap.php to locate the correct Composer autoload file automatically.

Each example has two parts:

1. a WebSocket server process;
2. a browser UI served by PHP's built-in HTTP server.

EasyChat

Start the WebSocket server:

Open another terminal and serve the UI:

If you installed the package inside another project with Composer, run:

Open:

EasyChat demonstrates:

• global chat;
• unique display names;
• presence;
• typing indicators;
• emoji picker;
• small attachments;
• safe message rendering.

MediumChat

Start the WebSocket server:

Open another terminal and serve the UI:

If you installed the package inside another project with Composer, run:

Open:

MediumChat demonstrates everything from EasyChat plus:

• server-side callbacks;
• low-level socket events;
• chat lifecycle logs;
• event panel in the browser;
• extensibility points for custom behavior.

PrivateChat

Start the WebSocket server:

Open another terminal and serve the UI:

If you installed the package inside another project with Composer, run:

Open:

PrivateChat demonstrates:

• global room;
• direct 1:1 conversations;
• private group rooms;
• selected participants;
• unread badges;
• attachments;
• emoji picker;
• message receipts;
• bot commands.

Try the bot commands:

Example Matrix

Laravel Integration

PHPSockets can be used inside Laravel applications through Composer package discovery.

Install the package:

Publish the configuration:

Check the package status:

Start the WebSocket chat server from Laravel:

Run SQL migrations when using a persistent storage driver:

The package registers:

• Micilini\PhpSockets\Laravel\PhpSocketsServiceProvider
• Micilini\PhpSockets\Laravel\PhpSocketsFacade
• phpsockets:serve
• phpsockets:migrate
• phpsockets:status

Example usage:

Laravel is optional. The native PHP core continues to work standalone.

Running PHPSockets in a Laravel Project

A Laravel app usually has two running processes:

Run the WebSocket server:

In another terminal:

Then your Laravel pages can connect to:

Hosting the Examples Through Laravel Routes

For a Laravel demo app, you can keep PHPSockets as the engine and let Laravel serve the example screens.

Recommended local package structure while developing PHPSockets inside a Laravel app:

After installing from Packagist, the package will live under:

The idea is:

The WebSocket server still runs in a separate process, which is the correct model for realtime applications.

Configuration

After publishing the Laravel config, config/phpsockets.php contains:

Example .env:

API Overview

Main server

Server events

Available high-level events

• user.joined
• user.left
• message.received
• message.sent
• room.created
• bot.responded

Available low-level socket events

• open
• close
• error

Storage

PHPSockets uses in-memory storage by default. This is perfect for examples, demos and development.

Available storage options:

SQLite migration example

Laravel migration command

Attachments

The examples support small file messages.

Attachment runtime directory

By default, PHPSockets stores temporary example attachments in a project-local directory:

You can override this location with:

This is especially useful for production deployments, Laravel apps, containers and Windows environments.

Supported MIME types:

Default max file size:

Attachment behavior:

• selecting a file does not send it immediately;
• the selected file appears as a pending attachment;
• the user can add a text caption;
• the file is sent only when the user clicks Send;
• delivered files include a download button;
• unsafe MIME types are rejected;
• files above the configured limit are rejected.

The initial transport uses JSON text-frame envelopes with base64 payloads over WebSocket. Larger uploads should use a future HTTP upload flow with WebSocket metadata messages.

Bot Hooks

PHPSockets includes a lightweight bot layer.

Bots can listen to text messages and return a response in the same conversation context.

Supported contexts:

• Global Room;
• Direct conversations;
• Private group rooms.

Example:

Register the bot:

Bots are intentionally simple in v1. They do not require any external AI API.

Protocol Notes

PHPSockets uses JSON text frames for chat messages.

Example client message:

Example server message:

Binary WebSocket frames are not accepted by the chat core in this version. File messages are transported as validated JSON text-frame envelopes.

Security Model

PHPSockets includes a practical safety baseline for examples and local-first applications:

• messages are rendered safely in the examples;
• user-provided text should not be rendered with unsafe innerHTML;
• display names are normalized and must be unique while online;
• payload size is limited;
• attachment size is limited;
• attachment MIME type is validated;
• users cannot send messages to rooms they do not belong to;
• private group messages are delivered only to room members;
• bot messages do not trigger infinite bot loops;
• malformed frames can be rejected with WebSocket close codes.

This package is a realtime foundation. Production applications should still add authentication, authorization, HTTPS/WSS, monitoring, rate limiting, persistent storage and infrastructure hardening.

Project Structure

Testing and Quality

Install development dependencies:

Validate the package:

Run tests:

Run static analysis:

Check code style:

Fix code style:

Run the full quality pipeline:

Legacy Code

The original 2016 implementation is preserved under:

The legacy code is kept for historical and educational purposes only. The modern Composer package lives in src/ and does not depend on the old structure.

Roadmap

Current v1 focus:

• native WebSocket core;
• realtime server runtime;
• chat kit;
• EasyChat, MediumChat and PrivateChat;
• private groups;
• storage adapters;
• small attachments;
• bot hooks;
• Laravel integration;
• documentation and Packagist release.

Future ideas:

• standalone CLI binary;
• WSS/TLS helper documentation;
• Redis adapter;
• multi-process scaling;
• chunked binary file transfer;
• HTTP upload + WebSocket metadata;
• JWT/auth adapters;
• Laravel dashboard;
• official Docker image;
• benchmarks.

Packagist Release Checklist

Before tagging a stable release:

Then:

Submit the repository to Packagist:

After Packagist detects the package, users can install it with:

Repository:

License

PHPSockets is open-sourced software licensed under the MIT license.

Credits

Created and maintained by Micilini.

Originally created in 2016 and rebuilt as a modern native PHP realtime foundation in 2026.