php-cmd/cmd-bus

CommandBus for Mezzio

0.3.0 2025-10-13 21:20 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• beberlei/assert: ^3.3
• psr/container: ^2.0

Requires (Dev)

• laminas/laminas-coding-standard: ^3.0.1
• laminas/laminas-servicemanager: ^4.0.0
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.5.42

Suggests

• laminas/laminas-servicemanager: Laminas\ServiceManager component

BSD-3-Clause

• commandbus
• mezzio
• php-cmd

README

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

Table of Contents

Core Components

• CmdBus - The main command bus implementation
• CmdBusInterface - Command bus contract
• MiddlewarePipe - Middleware pipeline management
• MiddlewarePipelineInterface - Pipeline contract
• CommandHandlerFactory - Factory for command handlers
• ConfigProvider - Laminas configuration provider
• Next - Pipeline delegation helper

Interfaces

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

Container Factories

• CmdBusFactory - Service factory for CmdBus
• CommandHandlerFactoryFactory - Factory for CommandHandlerFactory
• 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

Quick Start

Installation

composer require php-cmd/cmd-bus

Basic Configuration

// config/config.php
return [
    PhpCmd\CmdBus\ConfigProvider::class => [
        'command-map' => [
            App\Command\CreateUserCommand::class => App\Handler\CreateUserHandler::class,
        ],
        'middleware_pipeline' => [
            ['middleware' => \PhpCmd\CmdBus\Middleware\CommandHandlerMiddleware::class, 'priority' => 1],
        ],
    ],
];

Usage in Mezzio

// In a request handler or middleware
class UserHandler
{
    public function __construct(
        private \PhpCmd\CmdBus\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.