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.
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 config:publish vinelab/minionand head toapp/config/packages/vinelab/minion/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',
]
]
);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. -
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
});
// 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 C 610B rossbar.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.