walkor/webman: a PHP web framework built on Workerman

What walkor/webman is and who it is for

walkor/webman is a PHP web framework built on top of Workerman, an event-driven networking library. The README describes it in one line as a super high performance PHP framework developed on Workerman. That framing matters: webman is not a rewrite of PHP's request lifecycle into something unfamiliar, it is a way to keep writing PHP handlers while the process that serves them stays alive between requests.

The people this is aimed at are PHP developers who have outgrown the classic shared-nothing model. In a typical PHP-FPM deployment, every request spins up a process, bootstraps the framework, opens connections, handles the request and tears everything down. webman keeps the process running and reuses it. For an application that opens a database connection on every request, that difference is the whole point of the project.

It also matters for anything that needs a persistent connection. The repository's topic list includes websocket alongside high-performance, php and web-framework, so a WebSocket endpoint is a first-class use case rather than something bolted on. If your application is a REST API plus a live channel, webman is designed to host both.

What it is not is a general-purpose CMS or an application scaffold with opinions about your domain. The top-level entries are app/, config/, public/, support/, runtime/, start.php, composer.json, plus Docker and Windows helpers. That is a framework skeleton, and the rest is yours to build.

How the Workerman event loop changes the PHP request model

The mechanism is a long-running process. Instead of one process per request, webman runs under Workerman, which holds the process open and dispatches incoming connections to your handlers. The repository reflects this in its entry point: start.php is what the Docker image runs, and the compose file's command is php start.php start. That command name, start, is the Workerman convention for launching the worker set.

The practical consequence is that anything you initialize once stays initialized. Database connections, configuration arrays, and objects you build at boot are still there on the next request. This is the source of the performance claim in the README and also the source of the sharpest constraint, which is covered below.

Startup also changes shape. The Dockerfile installs the pcntl extension and explicitly enables it, because Workerman uses process control to fork and manage workers. The same Dockerfile enables opcache, which is what makes a long-lived process worth having: compiled PHP files stay compiled across requests rather than being re-parsed each time.

So the data flow is: Workerman accepts the connection, routes it into the webman application, your handler runs inside a process that has already booted, and the response goes back over the same connection. Nothing about that flow is unusual for an event-loop server. What is unusual is doing it in PHP, where the language's shared-nothing default has trained a generation of developers to assume state cannot persist.

Installing walkor/webman and running a first request

The README does not contain install commands. It links to an install page at workerman.net/doc/webman/install.html, and that page is where the project says to get the framework. What the repository does give you is a container setup that needs no install step at all, because the image is built from the repository itself.

The Dockerfile builds on php:8.3.22-cli-alpine, copies the production php.ini into place, installs pdo, pdo_mysql and pcntl, and enables opcache and pcntl. The working directory is /app. Note the sed line that rewrites the Alpine mirror to mirrors.aliyun.com; that is a China-oriented default and you may want to change it if you build elsewhere.

The compose file wires the image to a port and a command:

version: "3"
services:
  webman:
    build: .
    container_name: docker-webman
    restart: unless-stopped
    volumes:
      - "./:/app"
    ports:
      - "8787:8787"
    command: ["php", "start.php", "start" ]

Two details are worth pausing on. The volume mounts the repository root over /app, so the container runs your working copy rather than a baked-in snapshot. And the exposed port is 8787, which is the port you should expect to reach once the container is up.

Bring it up with Docker Compose, which reads that file and builds the image:

docker compose up

After the build finishes, the container starts php start.php start and the service listens on 8787. If you prefer to run outside Docker, the repository also ships start.php at the root, which is the entry point the compose command invokes; the install page linked from the README is the source for the PHP-side steps.

For Windows there are two extra files, windows.bat and windows.php, which the repository provides alongside the Unix entry point.

The long-lived process is the limitation, not a footnote

Every benefit of webman comes with a matching hazard, and the documentation's own emphasis on the Workerman model is where the hazard lives. In a shared-nothing PHP deployment, a leaked global variable, a mutated static, or a connection left in a bad state dies with the request. Under webman, the process survives, so it does not.

Concretely: if a handler assigns to a static property or a global and never resets it, the next request sees the old value. If a database connection enters a failed transaction state and the code does not roll back, the same connection is handed to the next request. If a handler throws a fatal error that the runtime does not catch at the worker level, the worker can die, and depending on how the worker set is configured, capacity drops until it is replaced.

This is not a webman defect. It is the price of the model, and it is the same price every event-loop PHP runtime charges. But it means the framework is the wrong tool for a codebase that was written assuming request isolation and cannot be audited for it. Migrating a large legacy application onto webman without checking for cross-request state is a way to produce bugs that appear only under concurrency and never reproduce locally.

A second boundary is operational. There is no per-request process boundary to isolate a bad deploy. You restart the worker set rather than letting new processes pick up new code, and the repository's start.php start command is the mechanism for that. Teams used to atomic deploys where old and new code coexist will need to think about what happens during the restart window.

Finally, the repository's Dockerfile targets php:8.3.22-cli-alpine and installs a fixed extension set. If your application needs an extension outside pdo, pdo_mysql and pcntl, you are editing the Dockerfile, not configuring the framework.

webman against a conventional PHP-FPM stack

The honest comparison is not against another framework's feature list, it is against the deployment model you are already running. A standard PHP application behind PHP-FPM and nginx gives you process isolation for free, a mature worker pool managed by the SAPI, and a mental model every PHP developer already has. It also bootstraps on every request, and it cannot hold a WebSocket connection open in the same process that serves your HTTP routes.

webman inverts those trade-offs. You get a persistent process, reusable connections and a WebSocket-capable runtime in one application, and you give up isolation and the assumption that a bad request cannot poison the next one. That is the real difference in approach, and it is a deployment decision more than a syntax decision.

If your workload is a low-traffic admin panel, the PHP-FPM model is simpler and the performance difference will not be visible. If your workload is a high-throughput API or a service holding thousands of concurrent connections, the per-request bootstrap cost in PHP-FPM becomes the dominant term, and that is exactly the case webman was built for.

Within the Workerman family itself, the distinction is scope. Workerman is the networking layer; webman is the framework layered on top of it, with app/, config/ and support/ directories that give the HTTP side structure. Choosing webman over raw Workerman is choosing routing, configuration and application layout over writing the dispatch yourself.

Maintenance, licensing and what a release upgrade costs

The repository is not archived. Its last push was on 2026-04-15, and the most recent releases listed are v2.2.3, v2.2.2 and v2.2.1, all dated 2026-02-24. The v2.2.x line therefore received three releases in a single day, which suggests either a rapid patch sequence or a release-tagging burst around one change; the repository does not say which, and the README does not document a changelog, an upgrade guide or a rollback procedure.

That silence is the practical cost. Upgrading a framework that runs as a long-lived process is not the same as upgrading a library in a PHP-FPM application. You cannot rely on a mixed fleet of old and new processes to smooth the transition, because the restart is the deploy. Without a documented rollback path, the safe procedure is to pin the version in composer.json and test the restart on a staging worker set before touching production.

The licence is MIT, stated both in the repository's LICENSE file and in the README's own LICENSE section, which reads that webman is open-sourced software licensed under the MIT. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice, and if you are redistributing webman inside a product you should read the LICENSE file yourself.

One more cost worth naming: the README is a link hub. Home page, documentation, install, questions, apps, sponsors and thanks are all external links, and the repository itself contains no usage guide. Everything about how to write a handler lives on workerman.net, not in the checkout. That is fine while the site is up and the version you are reading matches the version you installed, and it is a dependency you should be aware of.

Editorial conclusion

Adopt walkor/webman if you run PHP services that are read-heavy, hold connection state, or need a WebSocket endpoint in the same process as your HTTP routes, and if you can accept that every long-lived process must survive its own fatal errors. Do not adopt it if your codebase depends on per-request global state, or if you need a framework that installs from a repository template without reading the install page. Before committing, verify three things: which PHP version the current release supports, whether the extensions you need are installable in the php:8.3.22-cli-alpine base image, and whether the bundled Dockerfile's pdo, pdo_mysql and pcntl set covers your application. The repository itself gives you start.php and the config directory as the two places to read first.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. walkor/webman on GitHub