webman

webman Framework Development

webman is a high-performance, long-lived in-memory PHP framework built on workerman. Unlike PHP-FPM (bootstrap per request, tear down after response), correct webman code starts from understanding the resident-process model.

Core Mental Model: Resident Memory

After startup, a worker stays in memory and handles thousands of requests. Hard rules that follow:

1. Never exit / die: they kill the whole worker and drop every connection on that process.
2. Static properties / globals survive across requests: data written by the previous request can "leak" into the next. Keep request-scoped data in local variables, $request attributes, or support\Context under coroutines.
3. Singletons are shared across requests: do not store request state on singletons; array properties that only grow are memory leaks.
4. Code changes need reload/restart (php start.php reload). In debug mode, status / connections help diagnose issues.
5. Controllers are new per request by default (controller_reuse => false in config/app.php). If reuse is enabled, controller properties also survive across requests.

Project Layout

├── app/                  # Application code
│   ├── controller/       # Controllers (optional; MVC or DDD as you prefer)
│   ├── model/            # Models
│   ├── middleware/       # Middleware
│   └── functions.php     # Custom helpers
├── config/               # All configuration
│   ├── route.php         # Routes
│   ├── process.php       # Process definitions (HTTP, custom, timers)
│   ├── middleware.php    # Middleware registration
│   ├── database.php      # Database (illuminate/database)
│   ├── redis.php         # Redis
│   └── plugin/           # Plugin config
├── plugin/               # Application plugins
├── public/               # Static assets (only web-accessible directory)
├── process/              # Custom process classes
├── support/              # Framework bridge code
└── start.php             # Entry point

Common Commands

composer create-project workerman/webman   # create project

# Linux / macOS
php start.php start        # foreground (debug)
php start.php start -d     # daemon (production)
php start.php reload       # graceful reload (code updates, keep connections)
php start.php restart -d   # full restart (required after process.php, Timer, or resident data changes)
php start.php stop
php start.php status       # process memory, request counts
php start.php connections  # connection info

# Windows (no daemon / reload)
php windows.php

reload vs restart: reload only reloads app code (app/ and most of config/). Changes to config/process.php or timers/connections already created in onWorkerStart are not reloaded — use restart.

Coding Conventions

• PHP >= 8.0 (webman v2 requires 8.1+); always declare(strict_types=1).
• Controller signatures: public function action(Request $request): Response, with support\Request.
• Return Webman\Http\Response via helpers (response(), json(), view(), redirect(), …). Do not echo.
• Prefer illuminate/database (Db::table() / Eloquent models extending support\Model).
• Read config with config('app.debug'); never include config files.
• Log with support\Log (Log::info() / Log::channel('xx')->info()), not error_log or echo.

Do / Don't Cheatsheet

Don't	Do
exit() / die() to end a request	return response(...) or throw
$_GET / $_POST / $_SESSION	$request->get() / $request->post() / $request->session()
header() / setcookie()	$response->header() / $response->cookie()
Unbounded static arrays	Bounded cache (LRU) or Redis
Request data on singletons	Locals / support\Context (coroutines)
Timers created per request in app code	Custom process in config/process.php
Static vars for request state under coroutines	support\Context::set() / get()

References (read on demand)

• Routing, controllers, request/response APIs: references/routing-controller.md
• Middleware (onion model, CORS, auth): references/middleware.md
• Database, Redis, cache, pagination, transactions: references/database-redis.md
• Custom processes, WebSocket/TCP, timers: references/custom-process.md
• Coroutines (webman v2), Context, concurrency, pools: references/coroutine.md
• Lifecycle, memory leaks, prevention: references/memory-lifecycle.md
• Plugin development (library vs app plugins): references/plugin.md