Merge pull request #62 from tyrsson/refactor-target-config-keys

tyrsson · web-flow · commit a890ff2cfba1 · 2025-12-27T05:07:47.000-06:00
Refactor target config keys to CommandBusInteface::class
diff --git a/docs/command-handler-factory.md b/docs/command-handler-factory.md
@@ -125,9 +125,9 @@ class CustomCommandProcessor
 The factory relies on command-to-handler mappings configured in your application:
 
 ```php
-// config/autoload/cmd-bus.global.php
+// config/autoload/commandbus.global.php
 return [
-    Webware\CommandBus\ConfigProvider::class => [
+    Webware\CommandBus\CommandBusInterface::class => [
         'command-map' => [
             App\Command\CreateUserCommand::class => App\Handler\CreateUserHandler::class,
             App\Command\UpdateUserCommand::class => App\Handler\UpdateUserHandler::class,
@@ -142,7 +142,7 @@ return [
 Handlers must be registered in the dependency injection container:
 
 ```php
-// config/autoload/dependencies.global.php
+// In a autoloaded config file or ConfigProvider
 return [
     'dependencies' => [
         'factories' => [
diff --git a/docs/commandbus-interface.md b/docs/commandbus-interface.md
@@ -29,6 +29,7 @@ The `CommandBusInterface` serves as:
 1. **Abstraction Layer** - Allows different command bus implementations
 2. **Dependency Injection Target** - Services can depend on the interface rather than concrete implementations
 3. **Type Safety** - Provides compile-time guarantees for command handling
+4. **CommandBusInterface::class** - Serves as the top level configuration key
 
 ## Usage Examples
 
diff --git a/docs/config-provider.md b/docs/config-provider.md
@@ -69,7 +69,7 @@ $aggregator = new ConfigAggregator([
 ```php
 // config/autoload/cmd-bus.global.php
 return [
-    Webware\CommandBus\ConfigProvider::class => [
+    Webware\CommandBus\CommandBusInterface::class => [
         'command-map' => [
             // User management commands
             App\Command\User\CreateUserCommand::class => App\Handler\User\CreateUserHandler::class,
diff --git a/docs/container/commandbus-factory.md b/docs/container/commandbus-factory.md
@@ -196,9 +196,9 @@ try {
 The factory expects the middleware pipeline to be properly configured:
 
 ```php
-// config/autoload/cmd-bus.global.php
+// config/autoload/commandbus.global.php
 return [
-    'Webware\CommandBus\ConfigProvider' => [
+    CommandBusInterface::class => [
         'command-map' => [
             // Map command names to their handlers
             CreateUserCommand::class => CreateUserHandler::class,
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -30,7 +30,7 @@ $aggregator = new ConfigAggregator([
 use Webware\CommandBus\ConfigProvider;
 
 return [
-    ConfigProvider::class => [
+    CommandBusInterface::class => [
         ConfigProvider::COMMAND_MAP_KEY         => [
             App\User\Command\CreateUserCommand::class => App\User\CommandHandler\CreateUserHandler::class,
             App\User\Command\UpdateUserCommand::class => App\User\CommandHandler\UpdateUserHandler::class,
diff --git a/docs/middleware-pipe.md b/docs/middleware-pipe.md
@@ -58,7 +58,7 @@ Processes a command through the pipeline with a specific final handler.
 
 **Returns:**
 
-- `mixed` - The result from the pipeline execution
+- `CommandResultInterface` - The result from the pipeline execution
 
 ### pipe(MiddlewareInterface $middleware): void
 
diff --git a/docs/middleware/command-handler-middleware.md b/docs/middleware/command-handler-middleware.md
@@ -29,10 +29,10 @@ The middleware implements both `MiddlewareInterface` and `CommandHandlerInterfac
 ### Command-Handler Mapping
 
 ```php
-// config/autoload/cmd-bus.global.php
+// config/autoload/commandbus.global.php
 return [
     // other config
-    Webware\CommandBus\ConfigProvider::class => [
+    Webware\CommandBus\CommandBusInterface::class => [
         'command-map' => [
             App\Command\CreateUserCommand::class => App\Handler\CreateUserHandler::class,
             App\Command\UpdateUserCommand::class => App\Handler\UpdateUserHandler::class,
diff --git a/docs/middleware/post-command-handler-middleware.md b/docs/middleware/post-command-handler-middleware.md
@@ -211,9 +211,9 @@ final class ErrorHandlingPostCommandMiddleware extends PostCommandHandlerMiddlew
 ### Adding to Middleware Pipeline
 
 ```php
-// config/autoload/cmd-bus.global.php
+// config/autoload/commandbus.global.php
 return [
-    Webware\CommandBus\ConfigProvider::class => [
+    Webware\CommandBus\CommandBusInterface::class => [
         'middleware-pipeline' => [
             // Pre-command middleware...
             [
diff --git a/docs/middleware/pre-command-handler-middleware.md b/docs/middleware/pre-command-handler-middleware.md
@@ -124,9 +124,9 @@ final class EnrichmentPreCommandMiddleware extends PreCommandHandlerMiddleware
 ### Adding to Middleware Pipeline
 
 ```php
-// config/autoload/cmd-bus.global.php
+// config/autoload/commandbus.global.php
 return [
-    Webware\CommandBus\ConfigProvider::class => [
+    Webware\CommandBus\CommandBusInterface::class => [
         'middleware-pipeline' => [
             [
                 'middleware' => App\Middleware\AuthenticationPreCommandMiddleware::class,
diff --git a/src/CommandHandlerResolver.php b/src/CommandHandlerResolver.php
@@ -6,14 +6,15 @@
 
 use Override;
 use Psr\Container\ContainerInterface;
+use Webware\CommandBus\CommandBusInterface;
 use Webware\CommandBus\CommandInterface;
 use Webware\CommandBus\ConfigProvider;
 use Webware\CommandBus\Exception\InvalidConfigurationException;
 
 use function array_key_exists;
 
 /**
- * @phpstan-import-type CmdBusConfig from ConfigProvider
+ * @phpstan-import-type CommandBusConfig from ConfigProvider
  * @phpstan-import-type CommandMap from ConfigProvider
  */
 final class CommandHandlerResolver implements CommandHandlerResolverInterface
@@ -31,10 +32,10 @@ public function __invoke(CommandInterface $command): CommandHandlerInterface
     #[Override]
     public function resolve(CommandInterface $command): CommandHandlerInterface
     {
-        /** @phpstan-var array<CmdBusConfig> */
+        /** @phpstan-var array<CommandBusConfig> */
         $config = $this->container->get('config');
-        /** @phpstan-var CmdBusConfig $config */
-        $config = $config[ConfigProvider::class] ?? [];
+        /** @phpstan-var CommandBusConfig $config */
+        $config = $config[CommandBusInterface::class] ?? [];
         /** @phpstan-var CommandMap $map */
         $map = $config[ConfigProvider::COMMAND_MAP_KEY] ?? [];
         if (! array_key_exists($command::class, $map)) {
diff --git a/src/ConfigProvider.php b/src/ConfigProvider.php
@@ -15,7 +15,7 @@
  *     priority: int
  * }
  * @phpstan-type MiddlewarePipeSpec array<MiddlewareSpec>
- * @phpstan-type CmdBusConfig array{
+ * @phpstan-type CommandBusConfig array{
  *     command-map: CommandMap,
  *     middleware_pipeline: MiddlewarePipeSpec
  * }
@@ -73,14 +73,14 @@ final class ConfigProvider
     /**
      * @phpstan-return array{
      *     dependencies: ServiceManagerConfiguration,
-     *     Webware\CommandBus\ConfigProvider: CmdBusConfig,
+     *     Webware\CommandBus\CommandBusInterface: CommandBusConfig,
      * }
      */
     public function __invoke(): array
     {
         return [
-            'dependencies' => $this->getDependencies(),
-            static::class  => [
+            'dependencies'             => $this->getDependencies(),
+            CommandBusInterface::class => [
                 self::COMMAND_MAP_KEY         => $this->getCommandMap(),
                 self::MIDDLEWARE_PIPELINE_KEY => $this->getMiddleware(),
             ],
diff --git a/src/Container/MiddlewarePipeFactory.php b/src/Container/MiddlewarePipeFactory.php
@@ -6,6 +6,7 @@
 
 use Psr\Container\ContainerInterface;
 use SplPriorityQueue;
+use Webware\CommandBus\CommandBusInterface;
 use Webware\CommandBus\ConfigProvider;
 use Webware\CommandBus\Exception;
 use Webware\CommandBus\MiddlewareInterface;
@@ -17,7 +18,7 @@
 use function sprintf;
 
 /**
- * @phpstan-import-type CmdBusConfig from ConfigProvider
+ * @phpstan-import-type CommandBusConfig from ConfigProvider
  * @phpstan-import-type MiddlewarePipeSpec from ConfigProvider
  * @phpstan-import-type MiddlewareSpec from ConfigProvider
  * @phpstan-import-type CommandMap from ConfigProvider
@@ -30,16 +31,16 @@ public function __invoke(ContainerInterface $container): MiddlewarePipelineInter
             throw Exception\ServiceNotFoundException::fromService('config');
         }
 
-        /** @phpstan-var array<CmdBusConfig> $config */
+        /** @phpstan-var array<CommandBusConfig> $config */
         $config = $container->get('config');
-        /** @phpstan-var CmdBusConfig $config */
-        $config = $config[ConfigProvider::class] ?? [];
+        /** @phpstan-var CommandBusConfig $config */
+        $config = $config[CommandBusInterface::class] ?? [];
 
         if ($config === []) {
             throw Exception\InvalidConfigurationException::fromMissingKey(
                 sprintf(
                     'Configuration for key: %s was not found in the config service.',
-                    '$config[' . ConfigProvider::class . ']'
+                    '$config[' . CommandBusInterface::class . ']'
                 )
             );
         }
@@ -56,9 +57,9 @@ public function __invoke(ContainerInterface $container): MiddlewarePipelineInter
     }
 
     /**
-     * Pipe middleware into the CmdBus middleware pipeline.
+     * Pipe middleware into the CommandBus middleware pipeline.
      *
-     * @phpstan-param CmdBusConfig $config
+     * @phpstan-param CommandBusConfig $config
      */
     private static function pipeMiddleware(
         ContainerInterface $container,
diff --git a/test/integration/CommandBusTest.php b/test/integration/CommandBusTest.php
@@ -25,7 +25,7 @@
  * @phpstan-import-type CmdBusConfig from ConfigProvider
  * @phpstan-import-type CommandMap from ConfigProvider
  */
-final class CmdBusTest extends TestCase
+final class CommandBusTest extends TestCase
 {
     private ContainerInterface&ServiceManager $container;
 
@@ -40,10 +40,10 @@ protected function setUp(): void
             TestAssets\TestMiddlewareFirst::class  => InvokableFactory::class,
             TestAssets\TestMiddlewareSecond::class => InvokableFactory::class,
         ];
-        $config[ConfigProvider::class][ConfigProvider::COMMAND_MAP_KEY] = [
+        $config[CommandBusInterface::class][ConfigProvider::COMMAND_MAP_KEY] = [
             TestAssets\Command::class => TestAssets\CommandHandler::class,
         ];
-        $middleware     = $config[ConfigProvider::class][ConfigProvider::MIDDLEWARE_PIPELINE_KEY];
+        $middleware     = $config[CommandBusInterface::class][ConfigProvider::MIDDLEWARE_PIPELINE_KEY];
         $testMiddleware = [
             [
                 'middleware' => TestAssets\TestMiddlewareFirst::class,
@@ -54,11 +54,11 @@ protected function setUp(): void
                 'priority'   => -1,
             ],
         ];
-        $config[ConfigProvider::class][ConfigProvider::MIDDLEWARE_PIPELINE_KEY] = array_merge(
+        $config[CommandBusInterface::class][ConfigProvider::MIDDLEWARE_PIPELINE_KEY] = array_merge(
             $middleware,
             $testMiddleware
         );
-        $dependencies['services']['config']                                     = $config;
+        $dependencies['services']['config']                                          = $config;
 
         // @phpstan-ignore-next-line
         $this->container = new ServiceManager($dependencies);
diff --git a/test/unit/ConfigProviderTest.php b/test/unit/ConfigProviderTest.php
@@ -7,6 +7,7 @@
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\CoversMethod;
 use PHPUnit\Framework\TestCase;
+use Webware\CommandBus\CommandBusInterface;
 use Webware\CommandBus\ConfigProvider;
 use Webware\CommandBus\Middleware\CommandHandlerMiddleware;
 
@@ -42,13 +43,13 @@ public function testInvokeReturnsCorrectStructure(): void
         $config = ($this->configProvider)();
 
         $this->assertArrayHasKey('dependencies', $config);
-        $this->assertArrayHasKey(ConfigProvider::class, $config);
+        $this->assertArrayHasKey(CommandBusInterface::class, $config);
 
         $dependencies = $config['dependencies'];
         $this->assertArrayHasKey('aliases', $dependencies);
         $this->assertArrayHasKey('factories', $dependencies);
 
-        $cmdBusConfig = $config[ConfigProvider::class];
+        $cmdBusConfig = $config[CommandBusInterface::class];
         $this->assertArrayHasKey(ConfigProvider::COMMAND_MAP_KEY, $cmdBusConfig);
         $this->assertArrayHasKey(ConfigProvider::MIDDLEWARE_PIPELINE_KEY, $cmdBusConfig);
     }
diff --git a/test/unit/Container/MiddlewarePipeFactoryTest.php b/test/unit/Container/MiddlewarePipeFactoryTest.php
@@ -9,6 +9,7 @@
 use PHPUnit\Framework\TestCase;
 use Psr\Container\ContainerInterface;
 use ReflectionClass;
+use Webware\CommandBus\CommandBusInterface;
 use Webware\CommandBus\ConfigProvider;
 use Webware\CommandBus\Container\MiddlewarePipeFactory;
 use Webware\CommandBus\Exception\InvalidConfigurationException;
@@ -44,7 +45,7 @@ protected function setUp(): void
     public function testInvokeReturnsMiddlewarePipelineInterface(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [],
             ],
         ];
@@ -81,7 +82,7 @@ public function testInvokeThrowsExceptionWhenConfigServiceNotFound(): void
         ($this->factory)($this->container);
     }
 
-    public function testInvokeThrowsExceptionWhenConfigProviderKeyMissing(): void
+    public function testInvokeThrowsExceptionWhenCommandBusInterfaceKeyMissing(): void
     {
         $config = [];
 
@@ -99,7 +100,7 @@ public function testInvokeThrowsExceptionWhenConfigProviderKeyMissing(): void
 
         $this->expectException(InvalidConfigurationException::class);
         $this->expectExceptionMessage(
-            'Configuration for key: $config[Webware\CommandBus\ConfigProvider] was not found in the config service.'
+            'Configuration for key: $config[Webware\CommandBus\CommandBusInterface] was not found in the config service.' // phpcs:ignore
         );
 
         ($this->factory)($this->container);
@@ -108,7 +109,7 @@ public function testInvokeThrowsExceptionWhenConfigProviderKeyMissing(): void
     public function testInvokeWithEmptyMiddlewarePipelineConfig(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [],
             ],
         ];
@@ -133,7 +134,7 @@ public function testInvokeWithEmptyMiddlewarePipelineConfig(): void
     public function testInvokeWithMiddlewarePipelineConfiguration(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [
                     [
                         'middleware' => 'TestMiddleware1',
@@ -177,7 +178,7 @@ public function testInvokeWithMiddlewarePipelineConfiguration(): void
     public function testInvokeSkipsMiddlewareNotAvailableInContainer(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [
                     [
                         'middleware' => 'TestMiddleware1',
@@ -220,7 +221,7 @@ public function testInvokeSkipsMiddlewareNotAvailableInContainer(): void
     public function testInvokeThrowsExceptionWhenMiddlewareConfigMissingMiddlewareKey(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [
                     [
                         'priority' => 10,
@@ -253,7 +254,7 @@ public function testInvokeThrowsExceptionWhenMiddlewareConfigMissingMiddlewareKe
     public function testInvokeWithMiddlewareDefaultPriority(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [
                     [
                         'middleware' => 'TestMiddleware1',
@@ -291,7 +292,7 @@ public function testInvokeWithMiddlewareDefaultPriority(): void
     public function testFactoryCanBeInvokedMultipleTimes(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [],
             ],
         ];
@@ -325,7 +326,7 @@ public function testFactoryIsCallable(): void
     public function testInvokeWithNonIntegerPriorityDefaultsToOne(): void
     {
         $config = [
-            ConfigProvider::class => [
+            CommandBusInterface::class => [
                 ConfigProvider::MIDDLEWARE_PIPELINE_KEY => [
                     [
                         'middleware' => 'TestMiddleware1',
