A simplified client the WAMP v2 protocol (Web Application Messaging Protocol) with a handy command line tool - PHP WebSocket made easy.
Based on the great work put together by Thruway, Minion will give you the simplicity
and flexibility of running minion run and get a client running in no time. In addition to helping you structure
your application. See How It Works for details.
For a jump-start head over to the Quick Start Guide or read on for detailed docs. Or you may take a look at the Examples to get an idea about how this works.
Add the following to require in composer.json
"vinelab/minion": "*"Then run composer update to install.
- Add
Vinelab\Minion\MinionServiceProviderto theprovidersarray in yourapp.phpand you'll have aMinionfacade available throught your project. - The command line tool is available through artisan as
php artisan minion:runsee CLI - Run
php artisan vendor:publishand head toapp/config/minion.phpto configure your minion.
Configure the connection parameters you want your client to use when it connects to a WAMP router.
$m = new Minion():
$m->run(['realm' => 'myrealm', 'host' => 'some.host.ws', 'port' => 8182]);$m = new Minion();
$m->register('ChatProvider');
$m->register('MyApp\Providers\NotificationProvider'):
$m->run();You may also find it useful to list the providers in the config as such:
$m = new Minion();
$m->run(
[
'port' => 9876,
'host' => 'the.host',
'realm' => 'somerealm',
'register' => [
'ChatProvider',
'SomeOtherProvider'
'NotificationProvider',
]
]
);In existing applications it may be useful to be re-use an existing ReactPHP loop. You can pass in a LoopInterface like so:
$loop = React\EventLoop\Factory::create();
$m = new Minion();
$m->run([], $loop);The idea behind Minion is to help structure your application and get it ready for scale with real-time communication by using providers to register RPCs and publish and subscribe to topics with predefined functionalities to make things quick. For more about RPCs and Pub/Sub see Introduction to WAMP programming
WAMP is a protocol that defines a Router that handles connections of clients, your application is one
of these clients and the application logic is implemented within providers which you can
register with Minion using the register($provider) method. A provider can be the name of a class
(full namespace if applicable) or a Closure.
Consider the following directory structure:
src/
vendor/
start.php
composer.json
- Provider classes is where your application logic resides, Minion uses topic prefixes as a convention to distinguish
providers and that is done by specifying a
protected $prefix = 'topic.prefix.';in your provider class.
It is a convention to use dot '.' separated prefixes such as
chat.which will result in topicreadend up beingchat.read
-
Every provider class must extend
Vinelab\Minion\Providerand implementpublic function boot()method which is the best place to have your registrations and pub/sub operations. -
Every method registered or subscribed will receive the
$argsand$datawhen involved. Consider this methodpublic function get($args, $data)
$argsis the array of the args passed from the call$datais aDictionaryinstance where you can safely access attributes like$data->somethingand when they don't exist you get anullvalue instead of an error as inStdClassobjects, though you may use the$datavariable as you would use any other object withisset($data->prop)andempty($data->prop)
-
src/ChatProvider.php
<?php
use Vinelab\Minion\Provider;
class ChatProvider extends Provider
{
protected $prefix = 'chat.';
public function boot()
{
// will be registered to topic: chat.send
$this->register('send', 'sendMessage');
}
public function sendMessage($args, $data)
{
$message = $data->message;
// store message in the database
// tell everyone about it
$this->publish('message', compact('message'));
// response with the status
return true;
}
}start.php
use Vinelab\Minion\Minion;
$m = new Minion;
$m->register('ChatProvider');
$m->run();start.php
require __DIR__.'/vendor/autoload.php'
use Vinelab\Minion\Minion;
use Vinelab\Minion\Client;
// Get a minion instance
$m = new Minion;
$add = function ($x, $y) { return $x + $y; };
// Register a closure provider
$m->register(function (Client $client) use ($add) {
// register
$client->register('add', $add);
// subscribe
$client->subscribe('some.topic', function ($data) {
// do things with data
$data->key;
$data->other_key;
});
// publish
$client->publish('i.am.here', ['name' => 'mr.minion']);
});Minion comes with a handy command line tool for usage straight from the command line. Once you install using composer
a minion binary will be in your vendor/bin/. To make things easier you can run export PATH="./vendor/bin:$PATH"
to use minion run straight instead of ./vendor/bin/minion run
use minion list for a list of available commands and minion --help [command] for more info about each of them.
run- Options
--realm: Specify WAMP realm to be used--host: Specify the router host--port: Specify the router port--register: Register provider classes (can be used multiple times)
- Example
minion run --realm=chatting --port=9876 --register="ChatProvider" --register="MyApp\Providers\NotificationsProvider"
- Options
Minion ships with a minimal crossbar.io config file which you can find at
./vendor/vinelab/minion/.crossbar/config.json and to start crossbar using it run
crossbar start --cbdir ./vendor/vinelab/minion/.crossbar
To get started with Crossbar visit the Quick Start with Crossbar.io Guide.
For more information about crossbar head over to Crossbar.io Quick Start.
Pull Requests are most welcome! Dev packages are specified in composer.json under require-dev
- Run tests with
./vendor/bin/phpunit - Coding standards must be checked before committing code by issuing:
./vendor/bin/phpcs --standard=phpcs.xml src - In the case of violations use
./vendor/bin/php-cs-fixer fix srcwhich will help solve them out
Minion is distributed under the MIT License, see the LICENSE file in this package.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent