Merge pull request #3 from open-solid/decorators

add support for handler decorators

.php-cs-fixer.php

@@ -19,6 +19,7 @@
         '@Symfony' => true,
         'header_comment' => ['header' => $header],
         'declare_strict_types' => true,
+        'native_function_invocation' => true,
     ])
     ->setFinder($finder)
 ;

README.md

@@ -15,8 +15,9 @@ composer require open-solid/bus
 
 ### Dispatching Message with the Bus
 
-Think of the "bus" as a mail delivery system for your messages. It follows a specific path, decided 
-by some rules (middleware), to send your message and handle it.
+Think of the "bus" as a mail delivery system for your messages. It follows a 
+specific path, decided by some rules (middleware), to send your message and 
+handle it.
 
 Here's a snippet on how to set it up and dispatch a message:
 
@@ -44,8 +45,8 @@ $bus->dispatch(new MyMessage());
 
 ### Handling Messages
 
-A "message handler" is what does the work when a message arrives. It can be a simple function or a method in a class. 
-Here's how you set one up:
+A "message handler" is what does the work when a message arrives. It can be a simple 
+function or a method in a class. Here's how you set one up:
 
 ```php
 use App\Message\MyMessage;
@@ -61,9 +62,11 @@ class MyMessageHandler
 
 ### Middleware
 
-Middleware are helpers that do stuff before and after your message is handled. They can change the message or do other tasks.
+Middleware are helpers that perform tasks before and after your message is handled. They 
+operate at the bus level, meaning they handle all messages dispatched through the message 
+bus they are linked to.
 
-Here’s how to create one:
+Here's how to create one:
 
 ```php
 use OpenSolid\Bus\Envelope\Envelope;
@@ -76,13 +79,92 @@ class MyMiddleware implements Middleware
     {
         // Do something before the message handler works.
 
-        $next->handle($envelope); // Pass the message to the next middleware
+        $next->handle($envelope); // Call the next middleware
 
         // Do something after the message handler is done.
     }
 }
 ```
 
+### Decorators
+
+Decorators are helpers that perform tasks before and after your message is handled. Unlike
+Middleware, decorators operate at the handler level, allowing you to modify or enhance the 
+handler behavior without changing their actual code.
+
+Essentially, a decorator is a callable that takes another callable as an argument and extends 
+or alters its behavior. Let's see an example:
+
+```php
+use OpenSolid\Bus\Decorator\Decorator;
+
+class StopwatchDecorator implements Decorator
+{
+    public function decorate(\Closure $func): \Closure
+    {
+        return function (mixed ...$args) use ($func): mixed {
+            // do something before
+
+            $result = $func(...$args);
+
+            // do something after
+
+            return $result;
+        };
+    }
+} 
+```
+
+Then, use it wherever you want to decorate a message handler operation with 
+the `#[Decorate]` attribute, which configures the decorator that will wrap 
+the current `MyMessageHandler::__invoke()` method.
+
+```php
+use App\Decorator\StopwatchDecorator;
+use OpenSolid\Bus\Decorator\Decorate;
+
+class MyMessageHandler
+{
+    #[Decorate(StopwatchDecorator::class)]
+    public function __invoke(MyMessage $message): void
+    {
+        // ...
+    }
+}
+```
+
+If it's a frequently used decorator, you can create a pre-defined class 
+to avoid configuring the same decorator repeatedly:
+
+```php
+use App\Decorator\StopwatchDecorator;
+use OpenSolid\Bus\Decorator\Decorate;
+
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+readonly class Stopwatch extends Decorate
+{
+    public function __construct()
+    {
+        parent::__construct(StopwatchDecorator::class);
+    }
+}
+```
+
+Then, you can simply reference your `Stopwatch` attribute decorator as follows:
+
+```php
+use App\Decorator\Stopwatch;
+
+class MyMessageHandler
+{
+    #[Stopwatch]
+    public function __invoke(MyMessage $message): void
+    {
+        // ...
+    }
+}
+```
+
 ## Framework Integration
 
  * [cqs-bundle](https://github.com/open-solid/cqs-bundle) - Symfony bundle for Command-Query buses.

composer.json

@@ -29,7 +29,7 @@
         "vimeo/psalm": "^5.0",
         "phpunit/phpunit": "^10.0",
         "psalm/plugin-phpunit": "^0.18",
-        "symfony/dependency-injection": "^7.0",
+        "symfony/dependency-injection": "^7.1",
         "doctrine/orm": "^3.1",
         "friendsofphp/php-cs-fixer": "^3.54"
     },

docs/index.md

@@ -0,0 +1,2 @@
+# Message Bus Component
+

src/Bridge/Doctrine/Decorator/DoctrineTransactionDecorator.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of OpenSolid package.
+ *
+ * (c) Yonel Ceruto <open@yceruto.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace OpenSolid\Bus\Bridge\Doctrine\Decorator;
+
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\ManagerRegistry;
+use OpenSolid\Bus\Decorator\Decorator;
+
+class DoctrineTransactionDecorator implements Decorator
+{
+    private array $options = [];
+
+    public function __construct(
+        private readonly ManagerRegistry $registry,
+    ) {
+    }
+
+    public function decorate(\Closure $func): \Closure
+    {
+        $manager = $this->registry->getManager($this->options['name'] ?? null);
+
+        if (!$manager instanceof EntityManagerInterface) {
+            throw new \LogicException('Doctrine ORM entity managers are only supported');
+        }
+
+        return static function (mixed ...$args) use ($manager, $func): mixed {
+            return $manager->wrapInTransaction(static fn (): mixed => $func(...$args));
+        };
+    }
+
+    public function setOptions(array $options): void
+    {
+        $this->options = $options;
+    }
+}

src/Bridge/Doctrine/Decorator/Transactional.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of OpenSolid package.
+ *
+ * (c) Yonel Ceruto <open@yceruto.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace OpenSolid\Bus\Bridge\Doctrine\Decorator;
+
+use OpenSolid\Bus\Decorator\Decorate;
+
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+readonly class Transactional extends Decorate
+{
+    /**
+     * @param string|null $entityManagerName the entity manager name (null for the default one)
+     */
+    public function __construct(
+        ?string $entityManagerName = null,
+    ) {
+        parent::__construct(DoctrineTransactionDecorator::class, [
+            'name' => $entityManagerName,
+        ]);
+    }
+}

src/Bridge/Doctrine/Middleware/DoctrineTransactionMiddleware.php

@@ -14,19 +14,27 @@
 namespace OpenSolid\Bus\Bridge\Doctrine\Middleware;
 
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\ManagerRegistry;
 use OpenSolid\Bus\Envelope\Envelope;
 use OpenSolid\Bus\Middleware\Middleware;
 use OpenSolid\Bus\Middleware\NextMiddleware;
 
 final readonly class DoctrineTransactionMiddleware implements Middleware
 {
     public function __construct(
-        private EntityManagerInterface $em,
+        private ManagerRegistry $registry,
+        private ?string $entityManagerName = null,
     ) {
     }
 
     public function handle(Envelope $envelope, NextMiddleware $next): void
     {
-        $this->em->wrapInTransaction(fn () => $next->handle($envelope));
+        $manager = $this->registry->getManager($this->entityManagerName);
+
+        if (!$manager instanceof EntityManagerInterface) {
+            throw new \LogicException('Doctrine ORM entity managers are only supported');
+        }
+
+        $manager->wrapInTransaction(fn () => $next->handle($envelope));
     }
 }

src/Bridge/Symfony/DependencyInjection/CompilerPass/HandlingMiddlewarePass.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of OpenSolid package.
+ *
+ * (c) Yonel Ceruto <open@yceruto.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace OpenSolid\Bus\Bridge\Symfony\DependencyInjection\CompilerPass;
+
+use OpenSolid\Bus\Decorator\Decorate;
+use OpenSolid\Bus\Decorator\Decorator;
+use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
+use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Exception\LogicException;
+use Symfony\Component\DependencyInjection\Reference;
+
+final readonly class HandlingMiddlewarePass implements CompilerPassInterface
+{
+    use PriorityTaggedServiceTrait;
+
+    public function __construct(
+        private string $messageHandlerTagName,
+        private string $handlingMiddlewareId,
+        private array $exclude = [],
+        private bool $allowMultiple = false,
+        private string $topic = 'message',
+    ) {
+    }
+
+    public function process(ContainerBuilder $container): void
+    {
+        if (!$container->has($this->handlingMiddlewareId)) {
+            return;
+        }
+
+        $handlers = $this->findAndSortTaggedServices(
+            tagName: new TaggedIteratorArgument($this->messageHandlerTagName, 'class'),
+            container: $container,
+            exclude: $this->exclude,
+        );
+
+        $decorators = [];
+        foreach ($handlers as $messageClass => $refs) {
+            if (!$this->allowMultiple && \count($refs) > 1) {
+                throw new LogicException(\sprintf('Only one handler is allowed for %s of type "%s". However, %d were found: %s', $this->topic, $messageClass, \count($refs), implode(', ', $refs)));
+            }
+
+            foreach ($refs as $ref) {
+                /** @var class-string $handlerClass */
+                $handlerClass = $container->getDefinition((string) $ref)->getClass();
+
+                if (null === $refHandlerClass = $container->getReflectionClass($handlerClass)) {
+                    throw new LogicException('Missing reflection class.');
+                }
+
+                /** @var array<\ReflectionAttribute<Decorate>> $attributes */
+                $attributes = $refHandlerClass->getMethod('__invoke')->getAttributes(Decorate::class, \ReflectionAttribute::IS_INSTANCEOF);
+
+                foreach ($attributes as $attribute) {
+                    $instance = $attribute->newInstance();
+                    $decorator = $container->getDefinition($instance->id);
+                    /** @var class-string $decoratorClass */
+                    $decoratorClass = $decorator->getClass();
+
+                    if (!is_subclass_of($decoratorClass, Decorator::class)) {
+                        throw new LogicException(\sprintf('The handler decorator "%s" must implement the "%s" interface.', $decoratorClass, Decorator::class));
+                    }
+
+                    if (method_exists($decoratorClass, 'setOptions')) {
+                        $decorator->addMethodCall('setOptions', [$instance->options]);
+                    }
+
+                    $decorators[$handlerClass][$instance->id] = new Reference($instance->id);
+                }
+            }
+        }
+
+        $middleware = $container->findDefinition($this->handlingMiddlewareId);
+        $middleware->replaceArgument(0, new ServiceLocatorArgument($handlers));
+        $middleware->replaceArgument(1, new ServiceLocatorArgument($decorators));
+    }
+}