Web 4344 event machine behavior dependency injection

.gitignore

@@ -9,3 +9,4 @@ phpstan.neon
 testbench.yaml
 vendor
 node_modules
+.DS_Store

composer.json

@@ -52,7 +52,7 @@
         "profile": "vendor/bin/pest --profile --colors=always --order-by=random --configuration=phpunit.xml.dist",
         "coverage": "vendor/bin/pest --coverage --colors=always --order-by=random --configuration=phpunit.xml.dist",
         "coveragep": "vendor/bin/pest --parallel --coverage --colors=always --order-by=random --configuration=phpunit.xml.dist",
-        "pint": "vendor/bin/pint",
+        "pint": "vendor/bin/pint --config=pint.json",
         "lint": "@pint",
         "lintc": "vendor/bin/pint && (git diff-index --quiet HEAD || (git add . && git commit -m 'chore: Fix styling'))",
         "infection": "vendor/bin/infection --test-framework=pest --show-mutations --threads=max --min-msi=100 --min-covered-msi=100 --ansi"

src/Actor/Machine.php

@@ -165,16 +165,16 @@
         bool $shouldPersist = true,
     ): State {
         if ($this->state !== null) {
             $lock = Cache::lock('mre:'.$this->state->history->first()->root_event_id, 60);
         }
 
         if (isset($lock) && !$lock->get()) {
             throw MachineAlreadyRunningException::build($this->state->history->first()->root_event_id);
         }
 
         try {
             $lastPreviousEventNumber = $this->state !== null
                 ? $this->state->history->last()->sequence_number
                 : 0;
 
             // If the event is a string, we assume it's the event type.
@@ -224,12 +224,12 @@
         $lastHistoryEvent = $this->state->history->last();
 
         MachineEvent::upsert(
             values: $this->state->history->map(function (MachineEvent $machineEvent, int $index) use (&$incrementalContext, $lastHistoryEvent) {
                 // Get the context of the current machine event.
                 $changes = $machineEvent->context;
 
                 // If the current machine event is not the last one, compare its context with the incremental context and get the differences.
                 if ($machineEvent->id !== $lastHistoryEvent->id && $index > 0) {
                     $changes = $this->arrayRecursiveDiff($changes, $incrementalContext);
                 }
 
@@ -285,8 +285,8 @@
         $lastMachineEvent = $machineEvents->last();
 
         return new State(
             context: $this->restoreContext($lastMachineEvent->context),
             currentStateDefinition: $this->restoreCurrentStateDefinition($lastMachineEvent->machine_value),
             currentEventBehavior: $this->restoreCurrentEventBehavior($lastMachineEvent),
             history: $machineEvents,
         );
@@ -493,7 +493,7 @@
             $resultBehavior = new $resultBehavior();
         }
 
-        /* @var \Tarfinlabs\EventMachine\Behavior\ResultBehavior $resultBehavior */
+        /* @var callable $resultBehavior */
         return $resultBehavior(
             $this->state->context,
             $this->state->currentEventBehavior,

src/Actor/State.php

@@ -8,6 +8,7 @@
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Log;
 use Tarfinlabs\EventMachine\ContextManager;
+use Tarfinlabs\EventMachine\EventCollection;
 use Tarfinlabs\EventMachine\Enums\SourceType;
 use Tarfinlabs\EventMachine\Enums\InternalEvent;
 use Tarfinlabs\EventMachine\Models\MachineEvent;
@@ -41,9 +42,9 @@ public function __construct(
         public ContextManager $context,
         public ?StateDefinition $currentStateDefinition,
         public ?EventBehavior $currentEventBehavior = null,
-        public ?Collection $history = null,
+        public ?EventCollection $history = null,
     ) {
-        $this->history ??= (new MachineEvent())->newCollection();
+        $this->history ??= new EventCollection();
 
         $this->updateMachineValueFromState();
     }

src/Behavior/ActionBehavior.php

@@ -4,8 +4,6 @@
 
 namespace Tarfinlabs\EventMachine\Behavior;
 
-use Tarfinlabs\EventMachine\ContextManager;
-
 /**
  * ActionBehavior class.
  *
@@ -14,16 +12,4 @@
  */
 abstract class ActionBehavior extends InvokableBehavior
 {
-    /**
-     * Invokes the method with the given parameters.
-     *
-     * @param  ContextManager  $context Provides access to the context in which the method is being invoked.
-     * @param  EventBehavior  $eventBehavior The event behavior associated with the method invocation.
-     * @param  array|null  $arguments Optional parameters to be passed to the method.
-     */
-    abstract public function __invoke(
-        ContextManager $context,
-        EventBehavior $eventBehavior,
-        ?array $arguments = null,
-    ): void;
 }

src/Behavior/GuardBehavior.php

@@ -4,8 +4,6 @@
 
 namespace Tarfinlabs\EventMachine\Behavior;
 
-use Tarfinlabs\EventMachine\ContextManager;
-
 /**
  * Class GuardBehavior.
  *
@@ -14,18 +12,4 @@
  */
 abstract class GuardBehavior extends InvokableBehavior
 {
-    /**
-     * Invokes the method.
-     *
-     * @param  ContextManager  $context The context manager.
-     * @param  EventBehavior  $eventBehavior The event behavior.
-     * @param  array|null  $arguments The optional arguments for the method.
-     *
-     * @return bool Returns true if the method is invoked successfully, false otherwise.
-     */
-    abstract public function __invoke(
-        ContextManager $context,
-        EventBehavior $eventBehavior,
-        ?array $arguments = null,
-    ): bool;
 }

src/Behavior/InvokableBehavior.php

@@ -4,8 +4,12 @@
 
 namespace Tarfinlabs\EventMachine\Behavior;
 
+use ReflectionMethod;
+use ReflectionFunction;
+use ReflectionUnionType;
 use Illuminate\Support\Str;
 use Illuminate\Support\Collection;
+use Tarfinlabs\EventMachine\Actor\State;
 use Tarfinlabs\EventMachine\ContextManager;
 use Tarfinlabs\EventMachine\Exceptions\MissingMachineContextException;
 
@@ -30,33 +34,13 @@ abstract class InvokableBehavior
      *
      * @return void
      */
-    public function __construct(
-        protected ?Collection $eventQueue = null
-    ) {
+    public function __construct(protected ?Collection $eventQueue = null)
+    {
         if ($this->eventQueue === null) {
             $this->eventQueue = new Collection();
         }
     }
 
-    /**
-     * Executes the behavior with the given context and event.
-     *
-     * This method defines the contract for implementing behaviors
-     * within classes. The behavior should be directly invokable by
-     * passing in a ContextManager instance and an array of event payload.
-     *
-     * @param  ContextManager  $context The context to be used during
-     *                                                                        invocation.
-     * @param  \Tarfinlabs\EventMachine\Behavior\EventBehavior  $eventBehavior The event related to the
-     *                                                                        current behavior.
-     * @param  array|null  $arguments The arguments to be passed to the behavior.
-     */
-    abstract public function __invoke(
-        ContextManager $context,
-        EventBehavior $eventBehavior,
-        ?array $arguments = null,
-    );
-
     /**
      * Raises an event by adding it to the event queue.
      *
@@ -133,4 +117,54 @@ public static function getType(): string
             ->classBasename()
             ->toString();
     }
+
+    /**
+     * Injects invokable behavior parameters.
+     *
+     * Retrieves the parameters of the given invokable behavior and injects the corresponding values
+     * based on the provided state, event behavior, and action arguments.
+     * The injected values are added to an array and returned.
+     *
+     * @param  callable  $actionBehavior The invokable behavior to inject parameters for.
+     * @param  State  $state The state object used for parameter matching.
+     * @param  EventBehavior|null  $eventBehavior The event behavior used for parameter matching. (Optional)
+     * @param  array|null  $actionArguments The action arguments used for parameter matching. (Optional)
+     *
+     * @return array        The injected invokable behavior parameters.
+     *
+     * @throws \ReflectionException
+     */
+    public static function injectInvokableBehaviorParameters(
+        callable $actionBehavior,
+        State $state,
+        ?EventBehavior $eventBehavior = null,
+        ?array $actionArguments = null,
+    ): array {
+        $invocableBehaviorParameters = [];
+
+        $invocableBehaviorReflection = $actionBehavior instanceof self
+            ? new ReflectionMethod($actionBehavior, '__invoke')
+            : new ReflectionFunction($actionBehavior);
+
+        foreach ($invocableBehaviorReflection->getParameters() as $parameter) {
+            $parameterType = $parameter->getType();
+
+            $typeName = $parameterType instanceof ReflectionUnionType
+                ? $parameterType->getTypes()[0]->getName()
+                : $parameterType->getName();
+
+            $value = match (true) {
+                is_a($state->context, $typeName) => $state->context,    // ContextManager
+                is_a($eventBehavior, $typeName)  => $eventBehavior,     // EventBehavior
+                is_a($state, $typeName)          => $state,             // State
+                is_a($state->history, $typeName) => $state->history,    // EventCollection
+                $typeName === 'array'            => $actionArguments,   // Behavior Arguments
+                default                          => null,
+            };
+
+            $invocableBehaviorParameters[] = $value;
+        }
+
+        return $invocableBehaviorParameters;
+    }
 }

src/Behavior/ResultBehavior.php

@@ -4,13 +4,6 @@
 
 namespace Tarfinlabs\EventMachine\Behavior;
 
-use Tarfinlabs\EventMachine\ContextManager;
-
 abstract class ResultBehavior extends InvokableBehavior
 {
-    abstract public function __invoke(
-        ContextManager $context,
-        EventBehavior $eventBehavior,
-        ?array $arguments = null,
-    ): mixed;
 }

src/Behavior/ValidationGuardBehavior.php

@@ -4,8 +4,6 @@
 
 namespace Tarfinlabs\EventMachine\Behavior;
 
-use Tarfinlabs\EventMachine\ContextManager;
-
 /**
  * An abstract class that represents a validation guard behavior.
  *
@@ -18,19 +16,4 @@ abstract class ValidationGuardBehavior extends GuardBehavior
 {
     /** @var string|null Holds an error message, which is initially null. */
     public ?string $errorMessage = null;
-
-    /**
-     * Invokes the method.
-     *
-     * @param  ContextManager  $context The context manager.
-     * @param  EventBehavior  $eventBehavior The event behavior.
-     * @param  array|null  $arguments The arguments for the method (optional).
-     *
-     * @return bool Returns true if the method invocation was successful, false otherwise.
-     */
-    abstract public function __invoke(
-        ContextManager $context,
-        EventBehavior $eventBehavior,
-        ?array $arguments = null,
-    ): bool;
 }

src/Definition/MachineDefinition.php

@@ -684,6 +684,8 @@ public function transition(
      *
      * @param  string  $actionDefinition The action definition, either a class
      * @param  EventBehavior|null  $eventBehavior The event (optional).
+     *
+     * @throws \ReflectionException
      */
     public function runAction(
         string $actionDefinition,
@@ -720,8 +722,16 @@ public function runAction(
         // Get the number of events in the queue before the action is executed.
         $numberOfEventsInQueue = $this->eventQueue->count();
 
-        // Execute the action behavior.
-        $actionBehavior($state->context, $eventBehavior, $actionArguments);
+        // Inject action behavior parameters
+        $actionBehaviorParemeters = InvokableBehavior::injectInvokableBehaviorParameters(
+            actionBehavior: $actionBehavior,
+            state: $state,
+            eventBehavior: $eventBehavior,
+            actionArguments: $actionArguments
+        );
+
+        // Execute the action behavior
+        ($actionBehavior)(...$actionBehaviorParemeters);
 
         // Get the number of events in the queue after the action is executed.
         $newNumberOfEventsInQueue = $this->eventQueue->count();

src/Definition/TransitionBranch.php

@@ -166,6 +166,8 @@ protected function initializeInlineBehaviors(array $inlineBehaviors, BehaviorTyp
      * If there are no actions associated with the transition definition, do nothing.
      *
      * @param  EventBehavior|null  $eventBehavior The event or null if none is provided.
+     *
+     * @throws \ReflectionException
      */
     public function runActions(
         State $state,

src/Definition/TransitionDefinition.php

@@ -10,6 +10,7 @@
 use Tarfinlabs\EventMachine\Behavior\EventBehavior;
 use Tarfinlabs\EventMachine\Behavior\GuardBehavior;
 use Tarfinlabs\EventMachine\Enums\TransitionProperty;
+use Tarfinlabs\EventMachine\Behavior\InvokableBehavior;
 use Tarfinlabs\EventMachine\Behavior\ValidationGuardBehavior;
 
 /**
@@ -135,6 +136,8 @@ protected function isAMultiPathGuardedTransition(null|array|string $transitionCo
      *
      * @return TransitionDefinition|null The first eligible transition or
      *         null if no eligible transition is found.
+     *
+     * @throws \ReflectionException
      */
     public function getFirstValidTransitionBranch(
         EventBehavior $eventBehavior,
@@ -162,7 +165,18 @@ public function getFirstValidTransitionBranch(
                     $guardBehavior->validateRequiredContext($state->context);
                 }
 
-                if ($guardBehavior($state->context, $eventBehavior, $guardArguments) === false) {
+                // Inject guard behavior parameters
+                $guardBehaviorParameters = InvokableBehavior::injectInvokableBehaviorParameters(
+                    actionBehavior: $guardBehavior,
+                    state: $state,
+                    eventBehavior: $eventBehavior,
+                    actionArguments: $guardArguments,
+                );
+
+                // Execute the guard behavior
+                $guardResult = ($guardBehavior)(...$guardBehaviorParameters);
+
+                if ($guardResult === false) {
                     $guardsPassed = false;
 
                     $payload = null;

src/EventCollection.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tarfinlabs\EventMachine;
+
+use Illuminate\Database\Eloquent\Collection;
+
+class EventCollection extends Collection
+{
+}

src/Models/MachineEvent.php

@@ -6,6 +6,7 @@
 
 use Illuminate\Support\Carbon;
 use Illuminate\Database\Eloquent\Model;
+use Tarfinlabs\EventMachine\EventCollection;
 use Tarfinlabs\EventMachine\Enums\SourceType;
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
@@ -77,4 +78,20 @@ protected static function newFactory(): MachineEventFactory
     {
         return MachineEventFactory::new();
     }
+
+    /**
+     * Create a new collection of models.
+     *
+     * This method overrides the default Eloquent collection with a custom
+     * EventCollection. This allows for additional methods to be available
+     * on the collection of MachineEvent models.
+     *
+     * @param  array  $models An array of MachineEvent models.
+     *
+     * @return EventCollection A new instance of EventCollection.
+     */
+    public function newCollection(array $models = []): EventCollection
+    {
+        return new EventCollection($models);
+    }
 }

tests/ActionTest.php

@@ -29,11 +29,11 @@
         ],
         behavior: [
             'actions' => [
-                'additionAction' => function (ContextManager $context, EventDefinition $eventDefinition): void {
-                    $context->set('count', $context->get('count') + $eventDefinition->payload['value']);
+                'additionAction' => function (ContextManager $context, EventBehavior $eventBehavior): void {
+                    $context->set('count', $context->get('count') + $eventBehavior->payload['value']);
                 },
-                'subtractionAction' => function (ContextManager $context, EventDefinition $eventDefinition): void {
-                    $context->set('count', $context->get('count') - $eventDefinition->payload['value']);
+                'subtractionAction' => function (ContextManager $context, EventBehavior $eventBehavior): void {
+                    $context->set('count', $context->get('count') - $eventBehavior->payload['value']);
                 },
                 'incrementAction' => function (ContextManager $context): void {
                     $context->set('count', $context->get('count') + 1);
@@ -92,19 +92,15 @@
     $value = random_int(10, 20);
 
     $multipleWithItselfAction = new class extends ResultBehavior {
-        public function __invoke(
-            ContextManager $context,
-            EventBehavior $eventBehavior,
-            ?array $arguments = null
-        ): int {
-            return $eventBehavior->payload['value'] * $eventBehavior->payload['value'];
+        public function __invoke(EventBehavior $event): int
+        {
+            return $event->payload['value'] * $event->payload['value'];
         }
     };
 
     // 2. Act
     $result = $multipleWithItselfAction(
-        context: new ContextManager(),
-        eventBehavior: EventDefinition::from([
+        EventDefinition::from([
             'type'    => 'ADD',
             'payload' => [
                 'value' => $value,