feat: add autowiring via attributes to the command queue

Author: lindyhopchris

CHANGELOG.md

@@ -23,22 +23,28 @@ All notable changes to this project will be documented in this file. This projec
     - Integration events can now be mapped to handlers on an inbound event bus class via the `WithEvent` attribute.
     - The default handler can be set on the inbound event bus via the `WithDefault` attribute.
     - Middleware can now be added to an inbound event bus via the `Through` attribute.
-- New outbound event bus features, when using the publisher handler container:
-    - Can now use a PSR container for the outbound event bus to resolve both handlers and middleware. Inject the service
-      container via the first constructor argument.
-    - Integration events can now be mapped to handlers on a publisher handler container class via the `Publishes`
+- New outbound event bus features, when using the component publisher:
+    - Can now use a PSR container for the outbound event bus to resolve both publishers and middleware. Inject the
+      service container via the constructor.
+    - Integration events can now be mapped to publishers on a publisher handler container class via the `Publishes`
       attribute.
-    - The default handler can be set on the outbound event publisher via the `WithDefault` attribute.
-    - Middleware can now be added to a publisher handler container via the `Through` attribute.
+    - The default publisher can be set on the outbound event publisher via the `DefaultPublisher` attribute.
+    - Middleware can now be added to an outbound event publisher via the `Through` attribute.
+- New queue features, when using the component queue:
+    - Can now use a PSR container for the queue to resolve both enqueuers and middleware. Inject the service container
+      via the constructor.
+    - Commands can now be mapped to enqueuers on a publisher handler container class via the `Queues` attribute.
+    - The default enqueuer can be set on the outbound event publisher via the `DefaultEnqueuer` attribute.
+    - Middleware can now be added to the queue via the `Through` attribute.
 - In the Application layer, the `QueryHandlerContainer`, `CommandHandlerContainer` and `EventHandlerContainer` classes
   can now fallback to resolving handlers from a PSR service container. Inject the service container via their
   constructors.
-- In the Infrastructure layer, the `PublisherHandlerContainer` can now fallback to resolving handlers from a PSR service
-  container. Inject the service container via the constructor.
+- In the Infrastructure layer, the `PublisherHandlerContainer` and `EnqueuerContainer` can now fallback to resolving
+  handlers/enqueuers from a PSR service container. Inject the service container via the constructor.
+- The outbound event bus `ClosurePublisher` and the `ClosureQueue` classes now both accept a PSR container for their
+  middleware. Additionally, middleware can be set on instances of closure publishers via the `Through` attribute.
 - The pipeline `PipeContainer` class can now fallback to resolving pipes from a PSR service container. Inject the
   service container via the pipe container's only constructor argument.
-- The outbound event bus `ClosurePublisher` class now accepts a PSR container for its middleware. Additionally,
-  middleware can be set on instances of closure publishers via the `Through` attribute.
 - The `FakeUnitOfWork` class now has integer properties for the number of attempts, commits and rollbacks.
 - New `FakeContainer` class for faking a PSR container in tests.
 

src/Infrastructure/OutboundEventBus/ComponentPublisher.php

@@ -80,11 +80,11 @@ private function autowire(): void
         if ($this->handlers instanceof PublisherHandlerContainer) {
             foreach ($reflection->getAttributes(Publishes::class) as $attribute) {
                 $instance = $attribute->newInstance();
-                $this->handlers->bind($instance->event, $instance->handler);
+                $this->handlers->bind($instance->event, $instance->publisher);
             }
 
-            foreach ($reflection->getAttributes(WithDefault::class) as $attribute) {
-                $this->handlers->withDefault($attribute->newInstance()->handler);
+            foreach ($reflection->getAttributes(DefaultPublisher::class) as $attribute) {
+                $this->handlers->withDefault($attribute->newInstance()->publisher);
             }
         }
 

…ructure/OutboundEventBus/WithDefault.php …re/OutboundEventBus/DefaultPublisher.phpsrc/Infrastructure/OutboundEventBus/WithDefault.php renamed to src/Infrastructure/OutboundEventBus/DefaultPublisher.php src/Infrastructure/OutboundEventBus/WithDefault.php renamed to src/Infrastructure/OutboundEventBus/DefaultPublisher.php

@@ -15,12 +15,12 @@
 use Attribute;
 
 #[Attribute(Attribute::TARGET_CLASS)]
-final readonly class WithDefault
+final readonly class DefaultPublisher
 {
     /**
-     * @param class-string $handler
+     * @param non-empty-string $publisher
      */
-    public function __construct(public string $handler)
+    public function __construct(public string $publisher)
     {
     }
 }

src/Infrastructure/OutboundEventBus/Publishes.php

@@ -20,9 +20,9 @@
 {
     /**
      * @param class-string<IntegrationEvent> $event
-     * @param class-string $handler
+     * @param class-string $publisher
      */
-    public function __construct(public string $event, public string $handler)
+    public function __construct(public string $event, public string $publisher)
     {
     }
 }

src/Infrastructure/Queue/ClosureQueue.php

@@ -18,6 +18,9 @@
 use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer;
 use CloudCreativity\Modules\Toolkit\Pipeline\MiddlewareProcessor;
 use CloudCreativity\Modules\Toolkit\Pipeline\PipelineBuilder;
+use CloudCreativity\Modules\Toolkit\Pipeline\Through;
+use Psr\Container\ContainerInterface;
+use ReflectionClass;
 
 class ClosureQueue implements Queue
 {
@@ -33,8 +36,9 @@ class ClosureQueue implements Queue
 
     public function __construct(
         private readonly Closure $fn,
-        private readonly ?PipeContainer $middleware = null,
+        private readonly ContainerInterface|PipeContainer|null $middleware = null,
     ) {
+        $this->autowire();
     }
 
     /**
@@ -67,4 +71,13 @@ public function push(Command $command): void
 
         $pipeline->process($command);
     }
+
+    private function autowire(): void
+    {
+        $reflection = new ReflectionClass($this);
+
+        foreach ($reflection->getAttributes(Through::class) as $attribute) {
+            $this->pipes = $attribute->newInstance()->pipes;
+        }
+    }
 }

src/Infrastructure/Queue/ComponentQueue.php

@@ -13,23 +13,40 @@
 namespace CloudCreativity\Modules\Infrastructure\Queue;
 
 use CloudCreativity\Modules\Contracts\Application\Ports\Driven\Queue;
-use CloudCreativity\Modules\Contracts\Infrastructure\Queue\EnqueuerContainer;
+use CloudCreativity\Modules\Contracts\Infrastructure\Queue\EnqueuerContainer as IEnqueuerContainer;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
-use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer;
+use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer as IPipeContainer;
 use CloudCreativity\Modules\Toolkit\Pipeline\MiddlewareProcessor;
+use CloudCreativity\Modules\Toolkit\Pipeline\PipeContainer;
 use CloudCreativity\Modules\Toolkit\Pipeline\PipelineBuilder;
+use CloudCreativity\Modules\Toolkit\Pipeline\Through;
+use Psr\Container\ContainerInterface;
+use ReflectionClass;
 
 class ComponentQueue implements Queue
 {
+    private readonly IEnqueuerContainer $enqueuers;
+
+    private readonly ?IPipeContainer $middleware;
+
     /**
      * @var list<callable|string>
      */
     private array $pipes = [];
 
     public function __construct(
-        private readonly EnqueuerContainer $enqueuers,
-        private readonly ?PipeContainer $middleware = null,
+        ContainerInterface|IEnqueuerContainer $enqueuers,
+        ?IPipeContainer $middleware = null,
     ) {
+        $this->enqueuers = $enqueuers instanceof ContainerInterface ?
+            new EnqueuerContainer(container: $enqueuers) :
+            $enqueuers;
+
+        $this->middleware = $middleware === null && $enqueuers instanceof ContainerInterface
+            ? new PipeContainer($enqueuers)
+            : $middleware;
+
+        $this->autowire();
     }
 
     /**
@@ -53,4 +70,24 @@ public function push(Command $command): void
 
         $pipeline->process($command);
     }
+
+    private function autowire(): void
+    {
+        $reflection = new ReflectionClass($this);
+
+        if ($this->enqueuers instanceof EnqueuerContainer) {
+            foreach ($reflection->getAttributes(Queues::class) as $attribute) {
+                $instance = $attribute->newInstance();
+                $this->enqueuers->bind($instance->command, $instance->enqueuer);
+            }
+
+            foreach ($reflection->getAttributes(DefaultEnqueuer::class) as $attribute) {
+                $this->enqueuers->withDefault($attribute->newInstance()->enqueuer);
+            }
+        }
+
+        foreach ($reflection->getAttributes(Through::class) as $attribute) {
+            $this->pipes = $attribute->newInstance()->pipes;
+        }
+    }
 }

src/Infrastructure/Queue/DefaultEnqueuer.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Infrastructure\Queue;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final readonly class DefaultEnqueuer
+{
+    /**
+     * @param non-empty-string $enqueuer
+     */
+    public function __construct(public string $enqueuer)
+    {
+    }
+}

src/Infrastructure/Queue/EnqueuerContainer.php

@@ -15,40 +15,72 @@
 use Closure;
 use CloudCreativity\Modules\Contracts\Infrastructure\Queue\EnqueuerContainer as IEnqueuerContainer;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
+use CloudCreativity\Modules\Infrastructure\InfrastructureException;
+use Psr\Container\ContainerInterface;
 
 final class EnqueuerContainer implements IEnqueuerContainer
 {
     /**
-     * @var array<class-string<Command>, Closure>
+     * @var array<class-string<Command>, Closure|string>
      */
     private array $bindings = [];
 
     /**
-     * @param Closure(): object $default
+     * @param (Closure(): object)|string|null $default
      */
-    public function __construct(private readonly Closure $default)
-    {
+    public function __construct(
+        private Closure|string|null $default = null,
+        private readonly ?ContainerInterface $container = null,
+    ) {
+        if (is_string($this->default) && $this->container === null) {
+            throw new InfrastructureException(
+                'Cannot bind default enqueuer as a string without a PSR container.',
+            );
+        }
     }
 
     /**
      * Bind an enqueuer factory into the container.
      *
      * @param class-string<Command> $queueableName
-     * @param Closure(): object $binding
+     * @param (Closure(): object)|string $binding
      */
-    public function bind(string $queueableName, Closure $binding): void
+    public function bind(string $queueableName, Closure|string $binding): void
     {
         $this->bindings[$queueableName] = $binding;
     }
 
+    public function withDefault(Closure|string $binding): void
+    {
+        if ($this->default !== null) {
+            throw new InfrastructureException('Default enqueuer is already set.');
+        }
+
+        if (is_string($binding) && $this->container === null) {
+            throw new InfrastructureException(
+                'Cannot bind default enqueuer as a string without a PSR container.',
+            );
+        }
+
+        $this->default = $binding;
+    }
+
     public function get(string $command): Enqueuer
     {
-        $factory = $this->bindings[$command] ?? $this->default;
+        $binding = $this->bindings[$command] ?? $this->default;
 
-        $enqueuer = $factory();
+        if ($binding instanceof Closure) {
+            $instance = $binding();
+            assert(is_object($instance), "Enqueuer binding for command {$command} must return an object.");
+            return new Enqueuer($instance);
+        }
 
-        assert(is_object($enqueuer), "Enqueuer binding for {$command} must return an object.");
+        if (is_string($binding)) {
+            $instance = $this->container?->get($binding);
+            assert(is_object($instance), "PSR container enqueuer binding {$binding} is not an object.");
+            return new Enqueuer($instance);
+        }
 
-        return new Enqueuer($enqueuer);
+        throw new InfrastructureException('No enqueuer bound for command: ' . $command);
     }
 }

src/Infrastructure/Queue/Queues.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Infrastructure\Queue;
+
+use Attribute;
+use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final readonly class Queues
+{
+    /**
+     * @param class-string<Command> $command
+     * @param class-string $enqueuer
+     */
+    public function __construct(public string $command, public string $enqueuer)
+    {
+    }
+}

tests/Integration/Application/Bus/FloorCommand.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Tests\Integration\Application\Bus;
+
+use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
+
+final readonly class FloorCommand implements Command
+{
+    public function __construct(public float $number)
+    {
+    }
+}