#Chief

Chief is a powerful standalone command bus package for PHP 5.4+.

• What is a command bus
• Installation
• Usage
  • Class-based command handlers
  • Anonymous functions as command handlers
  • Self-handling commands
  • Decorators
  • Queued commands
  • Transactional commands
• Dependcy injection container integration
• License
• Contributing
• Author

The most common style of interface to a module is to use procedures, or object methods. So if you want a module to calculate a bunch of charges for a contract, you might have a BillingService class with a method for doing the calculation, calling it like this $billingService->calculateCharges($contract);. A command oriented interface would have a command class for each operation, and be called with something like this $cmd = new CalculateChargesCommand($contract); $cmd->execute();. Essentially you have one command class for each method that you would have in the method-oriented interface. A common variation is to have a separate command executor object that actually does the running of the command. $command = new CalculateChargesCommand($contract); $commandBus->execute($command);

-- From Martin Fowler's Blog (code samples haven ported to PHP):

That 'executor' Martin mentions is what we call the command bus. The pattern typically consists of 3 classes:

1. Command: A tiny object containing some data (probably just some public properties or getters/setters)
2. CommandHandler: Responsible for running the command through a handle($command) method
3. CommandBus: All commands are passed to the bus execute($command) method, which is responsible for finding the right CommandHandler and calling the handle($command) method.

For every Command in your application, there should be a corresponding CommandHandler.

In the below example, we demonstrate how a command bus design could handle registering a new user in your system using Chief:

useChief\Chief, Chief\Command; class RegisterUserCommand implements Command{public$email; public$name} class RegisterUserCommandHandler{publicfunctionhandle(RegisterUserCommand$command){Users::create([ 'email' => $command->email, 'name' => $command->name ]); Mailer::sendWelcomeEmail($command->email)} } $chief = newChief; $registerUserCommand = newRegisterUserCommand; $registerUserCommand->email = '[email protected]'; $registerUserCommand->name = 'Adam Nicholson'; $chief->execute($registerUserCommand);

Install the latest version with composer require chief/chief, or see Packagist.

No further setup is required, however if you're using a framework and want to make sure that we play nicely (with DI Containers, Event handlers, etc), then use the bridges below.

After installing via composer, add the below to the $providers array in your app/config/app.php:

'Chief\Bridge\Laravel\LaravelServiceProvider'

We'll use the below command/handler for the usage examples:

useChief\Chief, Chief\Command; class MyCommand implements Command{} class MyCommandHandler{publicfunctionhandle(MyCommand$command){/* ... */ } }

When you pass a Command to Chief::execute(), Chief will automatically search for the relevant CommandHandler and call the handle() method:

$chief = newChief; $chief->execute(newMyCommand);

By default, this will search for a CommandHandler with the same name as your Command, suffixed with 'Handler', in both the current namespace and in a nested Handlers namespace.

So Commands\FooCommand will automatically resolve to Commands\FooCommandHandler or Commands\Handlers\FooCommandHandler if either class exists.

Want to implement your own method of automatically resolving handlers from commands? Implement your own version of the Chief\CommandHandlerResolver interface to modify the automatic resolution behaviour.

If your handlers don't follow a particular naming convention, you can explicitly bind a command to a handler by its class name:

useChief\Chief, Chief\NativeCommandHandlerResolver, Chief\Busses\SynchronousCommandBus; $resolver = newNativeCommandHandlerResolver(); $bus = newSynchronousCommandBus($resolver); $chief = newChief($bus); $resolver->bindHandler('MyCommand', 'MyCommandHandler'); $chief->execute(newMyCommand);

Or, just pass your CommandHandler instance:

$resolver->bindHandler('MyCommand', newMyCommandHandler); $chief->execute(newMyCommand);

Sometimes you might want to quickly write a handler for your Command without having to write a new class. With Chief you can do this by passing an anonymous function as your handler:

$resolver->bindHandler('MyCommand', function (Command$command){/* ... */ }); $chief->execute(newMyCommand);

Alternatively, you may want to simply allow a Command object to execute itself. To do this, just ensure your Command class also implements CommandHandler:

class SelfHandlingCommand implements Command, CommandHandler{publicfunctionhandle(Command$command){/* ... */ } } $chief->execute(newSelfHandlingCommand);

Imagine you want to log every command execution. You could do this by adding a call to your logger in every CommandHandler, however a much more elegant solution is to use decorators.

Registering a decorator:

$chief = newChief(newSynchronousCommandBus, [newLoggingDecorator($logger)]);

Now, whenever Chief::execute() is called, the command will be passed to LoggingDecorator::execute(), which will perform some log action, and then pass the command to the relevant CommandHandler.

Chief provides you with two decorators out-the-box:

• LoggingDecorator: Log before and after all executions to a Psr\Log\LoggerInterface
• EventDispatchingDecorator: Dispatch an event to a Chief\Decorators\EventDispatcher after every command execution.
• CommandQueueingDecorator: Put the command into a Queue for later execution, if it implements Chief\QueueableCommand. (Read more under "Queued Commands")
• TransactionalCommandLockingDecorator: Lock the command bus when a command implementing Chief\TransactionalCommand is being executed. (Read more under "Transactional Commands")

Registering multiple decorators:

// Attach decorators when you instantiate$chief = newChief(newSynchronousCommandBus, [ newLoggingDecorator($logger), newEventDispatchingDecorator($eventDispatcher) ]); // Or attach decorators later$chief = newChief(); $chief->pushDecorator(newLoggingDecorator($logger)); $chief->pushDecorator(newEventDispatchingDecorator($eventDispatcher)); // Or manually stack decorators$chief = newChief( newEventDispatchingtDecorator($eventDispatcher, newLoggingDecorator($logger, $context, newCommandQueueingDecorator($queuer, newTransactionalCommandLockingDecorator( newCommandQueueingDecorator($queuer, newSynchronousCommandBus() ) ) ) ) ) );

Commands are often used for 'actions' on your domain (eg. send an email, create a user, log an event, etc). For these type of commands where you don't need an immediate response you may wish to queue them to be executed later. This is where the CommandQueueingDecorator comes in to play.

Firstly, to use the CommandQueueingDecorator, you must first implement the CommandQueuer interface with your desired queue package:

interface CommandQueuer{/** * Queue a Command for executing * * @param Command $command */publicfunctionqueue(Command$command)}

An implementation of CommandQueuer for illuminate/queue is included.

Next, attach the CommandQueueingDecorator decorator:

$chief = newChief(); $queuer = MyCommandBusQueuer(); $chief->pushDecorator(newCommandQueueingDecorator($queuer));

Then, implement QueueableCommand in any command which can be queued:

MyQueueableCommand implements Chief\QueueableCommand{}

Then use Chief as normal:

$command = newMyQueueableCommand(); $chief->execute($command);

If you pass Chief any command which implements QueueableCommand it will be added to the queue. Any commands which do not implement QueueableCommand will be executed immediately as normal.

If your commands implement QueueableCommand but you are not using the CommandQueueingDecorator, then they will be executed immediately as normal. For this reason, it is good practice to implement QueueableCommand for any commands which may be queued in the future, even if you aren't using the queueing decorator yet.

The CachingDecorator can be used to store the execution return value for a given command.

For example, you may have a FetchUerReportCommand, and an associated handler which takes a significant time to generate the "UserReport". Rather than re-generating the report every time, simply make FetchUserReport implement CacheableCommand, and the return value will be cached.

Data is cached to a psr/cache (PSR-6) compatible cache library.

Chief does not supply a cache library. You must require this yourself and pass it in as a consturctor argument to the CachingDecorator.

Example:

useChief\CommandBus, Chief\CacheableCommand, Chief\Decorators\CachingDecorator; $chief = newChief(); $chief->pushDecorator(newCachingDecorator( $cache, // Your library of preference implementing PSR-6 CacheItemPoolInterface.3600// Time in seconds that values should be cached for. 3600 = 1 hour. )); class FetchUserReportCommand implements CacheableCommand{} class FetchUserReportCommahdHandler{publicfunctionhandle(FetchUserReportCommand$command){return'foobar'} } $report = $chief->execute(newFetchUserReportCommand); // (string) "foo" handle() is called$report = $chief->execute(newFetchUserReportCommand); // (string) "foo" Value taken from cache$report = $chief->execute(newFetchUserReportCommand); // (string) "foo" Value taken from cache

Using the TransactionalCommandLockingDecorator can help to prevent more than 1 command being executed at any time. In practice, this means that you if you nest a command execution inside a command handler, the nested command will not be executed until the first command has completed.

Here's an example:

useChief\CommandBus; useChief\Command; useChief\Decorators\TransactionalCommandLockingDecorator; class RegisterUserCommandHandler{publicfunction__construct(CommandBus$bus, Users$users){$this->bus = $bus} publicfunctionhandle(RegisterUserCommand$command){$this->bus->execute(newRecordUserActivity('this-will-never-be-executed')); Users::create([ 'email' => $command->email, 'name' => $command->name ]); thrownewException('Something unexpected; could not create user')} } $chief = newChief(); $chief->pushDecorator(newTransactionalCommandLockingDecorator()); $command = newRegisterUserCommand; $command->email = '[email protected]'; $command->password = 'password123'; $chief->execute($command);

So what's happening here? When $chief->execute(new RecordUserActivity('registered-user')) is called, that command is actually dropped into an in-memory queue, which will not execute until RegisterCommandHandler::handle() has finished. In this example, because we're showing that an Exception is thrown before the method completes, the RecordUserActivity command is never actually executed.

Chief uses a CommandHandlerResolver class which is responsible for finding and instantiating the relevant CommandHandler for a given Command.

If you want to use your own Dependency Injection Container to control the actual instantiation, just create your own class which implements Chief\Container and pass it to the CommandHandlerResolver which is consumed by SynchronousCommandBus.

For example, if you're using Laravel:

useChief\Resolvers\NativeCommandHandlerResolver, Chief\Chief, Chief\Busses\SynchronousCommandBus, Chief\Container; class IlluminateContainer implements Container{publicfunctionmake($class){return \App::make($class)} } $resolver = newNativeCommandHandlerResolver(newIlluminateContainer); $chief = newChief(newSynchronousCommandBus($resolver)); $chief->execute(newMyCommand);

Containers have already been provided for :

Illuminate\Container:

$container = new \Illuminate\Container\Container; $resolver = newNativeCommandHandlerResolver(new \Chief\Bridge\Laravel\IlluminateContainer($container)); $chief = newChief(new \Chief\Busses\SynchronousCommandBus($resolver));

League\Container:

$container = new \League\Container\Container; $resolver = newNativeCommandHandlerResolver(new \Chief\Bridge\League\LeagueContainer($container)); $chief = newChief(new \Chief\Busses\SynchronousCommandBus($resolver));

We welcome any contributions to Chief. They can be made via GitHub issues or pull requests.

Chief is licensed under the MIT License - see the LICENSE.txt file for details

Adam Nicholson - [email protected]