From f849ac481a8bcd1c9634b5195353185737e5ada1 Mon Sep 17 00:00:00 2001 From: Christopher Vagnetoft Date: Fri, 1 Mar 2024 14:59:12 +0100 Subject: [PATCH] Updated readme, examples --- README.md | 61 +++++++++++++++++++++------------------------- examples/local.php | 26 ++++++++++++++------ 2 files changed, 46 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 958ce37..53e883a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,14 @@ # Command Bus for ReactPHP -* Can run monolithic (create a bus and use as is), or distributed (create bus and use clients), or a hybrid. +## Features + +* Can run monolithic (create a bus and use as is), or distributed (create bus and use clients), or in a hybrid setup. The CommandBus functions identical with or without clients. * All commands called asynchronously using promises and deferreds. +* Push notifications from the bus to subscribers and listeners, such as progress or log/error messages. (WIP) + +### Potential caveats + +* There is no security, nor encryption. This is intended to work between a daemon and a frontend, and is designed primarily considering all activity taking place on localhost. You can use ReactPHPs `SecureConnector` and `SecureServer` to encrypt the traffic, but this still allows anyone to connect and interact with the bus. If this sounds like something that should be changed, open a ticket. ## Installing @@ -12,41 +19,29 @@ $ composer require noccylabs/react-command-bus:^0.1.0 ## Usage ```php -// This is enough to setup a local bus. -$bus = new CommandBus(); -$bus->register('hello', function (Context $context) { +// The registry holds the callable commands +$commands = new CommandRegistry(); + +// Register some function to call. The name here is "hello", and it will +// receive a Context holding the call context. Any passed data will be +// available as properties on the Context object. +$commands->register("hello", function (Context $context) { + // You don't have to, but you should return a promise from your + // commands. return new Promise(function (callable $resolve) use ($context) { - return $resolve([ 'message' => "Hello, {$context->name}" ]); + Loop::addTimer(1, function () use ($context, $resolve) { + $resolve("Hello, {$context->name}"); + }); }); }); -// You can call it as expected -$bus->execute('hello', [ 'name' => "Bob" ]) - ->then(function (array $result) { - echo "Result: {$result['message']}\n"; - }); - -// Add a listener, and you can now connect to it! -$bus->addServer($server); - - -// So using this in another script works as expected, if you consider -// the async flow. See the examples for working examples. - -$client = new CommandBusClient(); -$client->connect($socket); - -$client->execute('hello', [ 'name' => "Bob" ]) - ->then(function (array $result) { - echo "Result: {$result['message']}\n"; - }); - - -// The bus can also notify all clients about important events -$bus->notify('updateCompleted', [ 'info' => [] ]); - -// Listening on the bus or client will yield the event -$bus->on('notify', function (string $event, array $data) {}); -$client->on('notify', function (string $event, array $data) {}); +// Create the bus +$bus = new CommandBus($commands); +// And execute some commands! +$bus->execute('hello', ['name'=>'Bob'])->then( + function ($result) { + var_dump($result); + } +); ``` diff --git a/examples/local.php b/examples/local.php index 70d5d46..0f8f16d 100644 --- a/examples/local.php +++ b/examples/local.php @@ -9,7 +9,12 @@ use React\EventLoop\Loop; use React\Promise\Promise; $commands = new CommandRegistry(); +// Register some function to call. The name here is "hello", and it will +// receive a Context holding the call context. Any passed data will be +// available as properties on the Context object. $commands->register("hello", function (Context $context) { + // You don't have to, but you should return a promise from your + // commands. return new Promise(function (callable $resolve) use ($context) { Loop::addTimer(1, function () use ($context, $resolve) { $resolve("Hello, {$context->name}"); @@ -17,17 +22,22 @@ $commands->register("hello", function (Context $context) { }); }); $commands->register("hello2", function (Context $context) { + // Just returning the value works just fine! return "Hello2, {$context->name}"; }); +// Create the bus $bus = new CommandBus($commands); -$bus->execute('hello', ['name'=>'Bob']) -->then(function ($result) { - var_dump($result); -}); +// And execute some commands! +$bus->execute('hello', ['name'=>'Bob'])->then( + function ($result) { + var_dump($result); + } +); -$bus->execute('hello2', ['name'=>'Bob']) -->then(function ($result) { - var_dump($result); -}); +$bus->execute('hello2', ['name'=>'Bob'])->then( + function ($result) { + var_dump($result); + } +);