README.md

cmd-bus Documentation

A Command Bus implementation for Mezzio applications, providing a clean way to handle commands through a middleware pipeline.

Table of Contents

Core Components

• CommandBus - The main command bus implementation
• CommandBusInterface - Command bus contract
• MiddlewarePipe - Middleware pipeline management
• MiddlewarePipelineInterface - Pipeline contract
• ConfigProvider - Laminas configuration provider
• Next - Pipeline delegation helper

Interfaces

• CommandInterface - Command contract
• CommandHandlerInterface - Handler contract
• MiddlewareInterface - Middleware contract

Container Factories

• CommandBusFactory - Service factory for CmdBus
• CommandHandlerMiddlewareFactory - Factory for CommandHandlerMiddleware
• MiddlewarePipeFactory - Factory for MiddlewarePipe

Middleware

• PreCommandHandlerMiddleware - Middleware for pre-processing commands
• CommandHandlerMiddleware - Final middleware for command execution
• PostCommandHandlerMiddleware - Middleware for post-processing results

Handlers

• EmptyPipelineHandler - Default handler for empty pipelines

Exceptions

• CommandException - Base command exception
• InvalidConfigurationException - Configuration errors
• NextHandlerAlreadyCalledException - Pipeline state errors
• ServiceNotFoundException - Service resolution errors

Getting Started

For a comprehensive guide to installation, configuration, and usage, see the Getting Started documentation. Full documentation for all components is available in the docs directory.

Quick Start

Installation

composer require webware/command-bus

Basic Configuration

// config/config.php
return [
    Webware\CommandBus\ConfigProvider::class => [
        'command_map' => [
            App\Command\CreateUserCommand::class => App\Handler\CreateUserHandler::class,
        ],
        'middleware_pipeline' => [
            ['middleware' => \Webware\CommandBus\Middleware\CommandHandlerMiddleware::class, 'priority' => 1],
        ],
    ],
];

Usage in Mezzio

// In a request handler or middleware
class UserHandler
{
    public function __construct(
        private \Webware\CommandBus\CmdBusInterface $commandBus
    ) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $data = $request->getParsedBody();

        $command = new CreateUserCommand(
            email: $data['email'],
            username: $data['username']
        );

        $user = $this->commandBus->handle($command);

        return new JsonResponse(['user' => $user->toArray()]);
    }
}

Architecture Overview

The cmd-bus library follows these key principles:

1. Commands are data objects that implement CommandInterface
2. Handlers process commands and implement CommandHandlerInterface
3. Middleware can intercept and potentially modify command processing
4. Pipeline manages middleware execution order
5. Factory classes integrate with Laminas ServiceManager/ Psr\Container\ContainerInterface

Contributing

See the project repository for contribution guidelines and development setup instructions.