Guide · Open source

How to use Workerman: install, run a WebSocket or HTTP server

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Workerman is an open-source PHP framework for writing network servers that handle many connections at once without blocking. This guide shows you how to install it, run WebSocket, HTTP and TCP servers, turn on SSL, and decide whether it fits your project. You should be able to start a working server on a POSIX system after following the steps below.

Workermanwalkor/workerman · ★ 11.5k · MIT Install options & downloads

Quick start

1Check your system. Confirm you are on Linux, OSX or BSD with PHP, the POSIX and PCNTL extensions, and Composer installed.
2Install the package. Run composer require workerman/workerman in your project folder.
3Write a server script. Create a PHP file that requires vendor/autoload.php and creates a Worker with an address such as websocket://0.0.0.0:2346.
4Attach event handlers. Set onConnect, onMessage and onClose callbacks to handle connections and data.
5Start the workers. Call Worker::runAll() at the end of the script and run the file with PHP from the command line.
6Add SSL if needed. Pass an ssl context with local_cert and local_pk, then set transport to ssl for wss://.

What do you need before installing Workerman?

Workerman runs on a POSIX-compatible operating system such as Linux, OSX or BSD. The README states that it does not target Windows.

You need PHP with the POSIX and PCNTL extensions enabled, and Composer to install the package. The Event, Swoole or Swow extensions are optional; the README recommends them for better performance.

A POSIX-compatible OS (Linux, OSX, BSD)
PHP with the POSIX and PCNTL extensions
Composer
Optional: Event, Swoole or Swow extension for better performance

How do you install Workerman with Composer?

Install the package from your project folder with the Composer command below. Composer creates the vendor directory, which your scripts load through vendor/autoload.php.

composer require workerman/workerman

How do you run a WebSocket server?

Create a PHP file, load the autoloader, and create a Worker bound to a websocket:// address. Attach handlers such as onConnect, onMessage and onClose, then call Worker::runAll() to start the workers. The example below listens on port 2346 and replies with a greeting to each message.

Start the script from the command line with PHP. The process stays running because Workerman is a long-lived process rather than a page that runs per request.

onConnect runs when a new connection arrives
onMessage runs when data is received and receives the connection and the data
onClose runs when a connection closes

<?php

use Workerman\Worker;

require_once __DIR__ . '/vendor/autoload.php';

// Create a Websocket server
$ws_worker = new Worker('websocket://0.0.0.0:2346');

// Emitted when new connection come
$ws_worker->onConnect = function ($connection) {
    echo "New connection\n";
};

// Emitted when data received
$ws_worker->onMessage = function ($connection, $data) {
    // Send hello $data
    $connection->send('Hello ' . $data);
};

// Emitted when connection closed
$ws_worker->onClose = function ($connection) {
    echo "Connection closed\n";
};

// Run worker
Worker::runAll();

How do you run an HTTP or TCP server?

The HTTP example listens on port 2345 and sets $http_worker->count to 4, which starts four processes. The request object exposes methods such as get, post, header, cookie, session, uri, path and method. The TCP example works the same way on port 1234 and uses a raw data callback.

The README's examples are minimal. For production options, the README points to the official manual at manual.workerman.net.

HTTP: new Worker('http://0.0.0.0:2345') with count set to 4
TCP: new Worker('tcp://0.0.0.0:1234') with count set to 4

use Workerman\Worker;

require_once __DIR__ . '/vendor/autoload.php';

// #### http worker ####
$http_worker = new Worker('http://0.0.0.0:2345');

// 4 processes
$http_worker->count = 4;

// Emitted when data received
$http_worker->onMessage = function ($connection, $request) {
    // Send data to client
    $connection->send("Hello World");
};

// Run all workers
Worker::runAll();

How do you enable SSL for secure WebSocket (wss)?

Pass an SSL context with paths to your certificate and private key, then set the worker's transport to ssl. The README says this combination gives you Secure WebSocket (wss://), and that HTTPS works in a similar way. Replace the placeholder paths with the real locations of your files.

local_cert: path to your server certificate
local_pk: path to your private key
verify_peer: set to false in the README example

$context = [
    'ssl' => [
        'local_cert'  => '/your/path/of/server.pem',
        'local_pk'    => '/your/path/of/server.key',
        'verify_peer' => false,
    ]
];

$ws_worker = new Worker('websocket://0.0.0.0:2346', $context);
$ws_worker->transport = 'ssl';

What are coroutines, Barrier, Parallel and Channel used for?

The README documents coroutine helpers for concurrent work inside a request. Coroutines require the Swoole or Swow extension, or Fiber with the revolt/event-loop package, and you select one by setting the worker's eventLoop property.

Barrier waits until a group of tasks finishes. Parallel runs tasks and returns each result in order. Channel passes data between coroutines. The README's Parallel example returns results such as ["Task 1 Done","Task 2 Done"].

Coroutine: runs asynchronous tasks concurrently
Barrier: waits for all tasks to finish
Parallel: runs tasks and collects their results
Channel: passes data between coroutines

$worker->eventLoop = Swoole::class; // Or Swow::class or Fiber::class

What people use it for

Real-time chat rooms over WebSocket
Push messaging and live notifications to connected clients
Custom TCP or binary protocol services written in PHP
Long-running HTTP services that handle many concurrent requests

Frequently asked questions

Is Workerman free to use?

Yes. Workerman is released under the MIT licence, as listed on its package page. Check the licence file in the repository before shipping a commercial product.

Does Workerman run on Windows?

The README says Workerman requires a POSIX-compatible operating system such as Linux, OSX or BSD. On Windows, use a Linux environment such as WSL or a Linux server.

What do I need to install Workerman?

You need PHP with the POSIX and PCNTL extensions and Composer. Install the package with composer require workerman/workerman.

How is Workerman different from a normal PHP website?

Workerman runs as its own long-lived process that keeps connections open. A standard request-per-page PHP site starts and stops for each request, so it does not need this model.

What are the alternatives to Workerman?

Comparable projects named in this directory are Swoole, ReactPHP, Ratchet and Amp. Each takes a different approach to event-driven PHP, so compare them against your protocol and platform needs.

Where can I find the full documentation?

The README links to the official manual at manual.workerman.net, which covers features beyond the basic examples in this guide.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Workerman suits PHP developers who need long-running WebSocket, TCP or HTTP servers and can run on Linux, OSX or BSD. Teams without PHP experience, Windows-only environments, and projects that just need ordinary page-by-page PHP should choose a different approach.

Install options & downloads