README

The Workerman driver behind plato\server\driver: the event loop, the protocol and the worker processes PlatoPHP deliberately does not ship.

简体中文

lumnd/platophp owns what happens between an inbound message and a controller — one whole message, one ct / ac dispatch, clean request state, an identity that was established once and belongs to the connection. It owns none of the socket: an event loop, a process manager and a protocol codec are not a framework's business, and a protocol parser is the part of the stack where a mistake is a remote memory exhaustion rather than a wrong page. This package is the other half of that seam, and nothing above plato\server\driver knows it is here.

Requirements

Install

composer require lumnd/plato-workerman

The shipped config/server.php already names workerman as its driver, so a default installation starts:

php vendor/bin/plato server:start

after the one line that registers the commands, below.

Configure

Everything the framework does not own in config/server.php is passed to this adapter untouched. Copy the file into your application's config/ and change what you need:

return [
    'default' => 'default',

    'servers' => [
        'default' => [
            // 'workerman' is registered by this package; the class name works just as well and
            // needs no bootstrap file at all
            'driver' => 'workerman',

            'listen'    => 'websocket://127.0.0.1:8282',
            'name'      => 'platophp-server',
            'processes' => 4,

            'heartbeat' => ['interval' => 30, 'timeout' => 120],

            // Read by plato\server\dispatcher, not by this adapter
            'dispatch' => ['max_payload' => 65536],
        ],
    ],
];

TLS is ssl.local_cert plus a websocket:// listener — that combination is wss. Terminating TLS at a reverse proxy and binding 127.0.0.1 is the usual arrangement, and the one to prefer.

Protocols

dispatcher::handle() takes one whole application message. Which protocol delivers it is this adapter's business and not the framework's, so several do:

and some do not:

Each is refused at start with a message saying which of these it is, rather than with a connection that half works.

Run it

Register the commands once, in plato.config.php or under console.commands in config/config.php:

'commands' => [plato\workerman\console::class],

php vendor/bin/plato server:start                    # foreground, until a signal
php vendor/bin/plato server:start --daemon           # detached
php vendor/bin/plato server:start --server=chat --processes=8
php vendor/bin/plato server:reload                   # new code, same listening socket
php vendor/bin/plato server:stop                     # --force to skip the graceful wait
php vendor/bin/plato server:status
php vendor/bin/plato server:connections

server:start is a foreground process on purpose, and belongs under something that keeps it running:

[Service]
ExecStart=/usr/bin/php /srv/app/vendor/bin/plato server:start
Restart=always
KillSignal=SIGTERM
TimeoutStopSec=40

An application that would rather not use the console calls the facade itself, which is all the command does:

plato\server\server::start();

Write the application

An action reached over a socket is an ordinary action. It reads its input through req, asks who the caller is through plato::$auth, and returns a plato\http\reply:

namespace control;

use plato\http\resp;
use plato\plato;
use plato\server\dispatcher;

class ctl_chat
{
    public function say()
    {
        // The identity was established at open and belongs to the connection
        $user = plato::$auth;

        // Reach this client again from anywhere in the process
        dispatcher::current()->send(['code' => 0, 'msg' => 'delivered']);

        return resp::json(['code' => 0, 'seq' => dispatcher::seq()]);
    }
}

Authentication happens once, at open. On a websocket the only thing a client has to authenticate with is the handshake — the frames that follow carry no headers — so this adapter puts it on the connection under driver::HANDSHAKE:

use plato\server\connection;
use plato\server\dispatcher;
use plato\workerman\driver;

dispatcher::on('open', function (connection $conn)
{
    $handshake = (array) $conn->get(driver::HANDSHAKE, []);
    $user      = my_auth((string) ($handshake['query']['token'] ?? ''));

    if ( $user === null )
    {
        // The driver closes the connection
        return false;
    }

    // Every later message of this client is dispatched as this identity
    $conn->set(connection::AUTH, $user);

    return true;
});

handshake is ['path' => string, 'query' => array, 'headers' => array], with lower case header names, on both Workerman majors. A protocol that has no handshake — a framed tcp:// listener — sets no attribute at all.

Processes

Every worker calls plato\worker::enter() before it serves anything, so an application shards work the same way it does under plato\pool:

'on_worker_start' => function (int $index, int $count)
{
    // Exactly one worker of this listener runs the sweep
    if ( plato\worker::owns() )
    {
        Workerman\Timer::add(60, 'my_sweep');
    }
},

Two things the framework says out loud, and this adapter keeps to:

• One message at a time per process. Request state lives in static properties, so a coroutine scheduler running two dispatches inside one pid corrupts it. Workerman 5's Fiber, Swoole and Swow loops are refused rather than half supported.
• send() reaches this process only. Workers do not share memory, and neither driver::connections() nor server::send() pretends otherwise. Fanning out to every worker needs a backend both can see — Redis pub/sub, or another external bus.

Tests

composer test          # Unit + Feature
composer analyse       # phpstan level 5, no baseline
composer style         # phpcs, zero errors

The feature suite starts real listeners in child processes and talks to them over real sockets with a hand written websocket handshake and hand written frames — a client that shared its framing code with the server would prove nothing about the wire.

License

MIT. Security reports go to the address in SECURITY.md.