Introduce step run args to simplify step run arguments

[MAILPOET-4629]

mailpoet/lib/Automation/Engine/Control/StepHandler.php

@@ -5,6 +5,7 @@ namespace MailPoet\Automation\Engine\Control;
 use Exception;
 use MailPoet\Automation\Engine\Control\Steps\ActionStepRunner;
 use MailPoet\Automation\Engine\Data\Step;
+use MailPoet\Automation\Engine\Data\StepRunArgs;
 use MailPoet\Automation\Engine\Data\SubjectEntry;
 use MailPoet\Automation\Engine\Data\WorkflowRun;
 use MailPoet\Automation\Engine\Data\WorkflowRunLog;
@@ -133,7 +134,8 @@ class StepHandler {
       try {
         $requiredSubjects = $step instanceof Action ? $step->getSubjectKeys() : [];
         $subjectEntries = $this->getSubjectEntries($workflowRun, $requiredSubjects);
-        $this->stepRunners[$stepType]->run($workflow, $workflowRun, $step, $subjectEntries);
+        $args = new StepRunArgs($workflow, $workflowRun, $step, $subjectEntries);
+        $this->stepRunners[$stepType]->run($args);
         $log->markCompletedSuccessfully();
       } catch (Throwable $e) {
         $log->markFailed();

mailpoet/lib/Automation/Engine/Control/StepRunner.php

@@ -2,12 +2,8 @@
 
 namespace MailPoet\Automation\Engine\Control;
 
-use MailPoet\Automation\Engine\Data\Step;
+use MailPoet\Automation\Engine\Data\StepRunArgs;
-use MailPoet\Automation\Engine\Data\SubjectEntry;
-use MailPoet\Automation\Engine\Data\Workflow;
-use MailPoet\Automation\Engine\Data\WorkflowRun;
 
 interface StepRunner {
-  /** @var SubjectEntry[] $subjectEntries */
+  public function run(StepRunArgs $args): void;
-  public function run(Step $step, Workflow $workflow, WorkflowRun $workflowRun, array $subjectEntries): void;
 }

mailpoet/lib/Automation/Engine/Control/Steps/ActionStepRunner.php

@@ -3,10 +3,7 @@
 namespace MailPoet\Automation\Engine\Control\Steps;
 
 use MailPoet\Automation\Engine\Control\StepRunner;
-use MailPoet\Automation\Engine\Data\Step;
+use MailPoet\Automation\Engine\Data\StepRunArgs;
-use MailPoet\Automation\Engine\Data\SubjectEntry;
-use MailPoet\Automation\Engine\Data\Workflow;
-use MailPoet\Automation\Engine\Data\WorkflowRun;
 use MailPoet\Automation\Engine\Exceptions\InvalidStateException;
 use MailPoet\Automation\Engine\Registry;
 
@@ -20,15 +17,14 @@ class ActionStepRunner implements StepRunner {
     $this->registry = $registry;
   }
 
-  /** @param SubjectEntry[] $subjectEntries */
+  public function run(StepRunArgs $args): void {
-  public function run(Step $step, Workflow $workflow, WorkflowRun $workflowRun, array $subjectEntries): void {
+    $action = $this->registry->getAction($args->getStep()->getKey());
-    $action = $this->registry->getAction($step->getKey());
     if (!$action) {
       throw new InvalidStateException();
     }
-    if (!$action->isValid($workflowRun->getSubjects(), $step, $workflow)) {
+    if (!$action->isValid($args->getWorkflowRun()->getSubjects(), $args->getStep(), $args->getWorkflow())) {
       throw new InvalidStateException();
     }
-    $action->run($workflow, $workflowRun, $step);
+    $action->run($args);
   }
 }

mailpoet/lib/Automation/Engine/Data/StepRunArgs.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types = 1);
+
+namespace MailPoet\Automation\Engine\Data;
+
+use MailPoet\Automation\Engine\Exceptions;
+use MailPoet\Automation\Engine\Workflows\Payload;
+use MailPoet\Automation\Engine\Workflows\Subject;
+
+class StepRunArgs {
+  /** @var Workflow */
+  private $workflow;
+
+  /** @var WorkflowRun */
+  private $workflowRun;
+
+  /** @var Step */
+  private $step;
+
+  /** @var array<string, SubjectEntry<Subject<Payload>>[]> */
+  private $subjectEntries = [];
+
+  /** @param SubjectEntry<Subject<Payload>>[] $subjectsEntries */
+  public function __construct(
+    Workflow $workflow,
+    WorkflowRun $workflowRun,
+    Step $step,
+    array $subjectsEntries
+  ) {
+    $this->workflow = $workflow;
+    $this->step = $step;
+    $this->workflowRun = $workflowRun;
+
+    foreach ($subjectsEntries as $entry) {
+      $subject = $entry->getSubject();
+      $key = $subject->getKey();
+      $this->subjectEntries[$key] = array_merge($this->subjectEntries[$key] ?? [], [$entry]);
+    }
+  }
+
+  public function getWorkflow(): Workflow {
+    return $this->workflow;
+  }
+
+  public function getWorkflowRun(): WorkflowRun {
+    return $this->workflowRun;
+  }
+
+  public function getStep(): Step {
+    return $this->step;
+  }
+
+  /** @return SubjectEntry<Subject<Payload>> */
+  public function getSingleSubjectEntry(string $key): SubjectEntry {
+    $subjects = $this->subjectEntries[$key] ?? [];
+    if (count($subjects) === 0) {
+      throw Exceptions::subjectDataNotFound($key, $this->workflowRun->getId());
+    }
+    if (count($subjects) > 1) {
+      throw Exceptions::multipleSubjectsFound($key, $this->workflowRun->getId());
+    }
+    return $subjects[0];
+  }
+}

mailpoet/lib/Automation/Engine/Exceptions.php

@@ -140,11 +140,13 @@ class Exceptions {
       );
   }
 
-  public static function multipleSubjectsFound(string $key): InvalidStateException {
+  public static function multipleSubjectsFound(string $key, int $workflowRunId): InvalidStateException {
     return InvalidStateException::create()
       ->withErrorCode(self::MULTIPLE_SUBJECTS_FOUND)
-      // translators: %s is the name of the key.
+      // translators: %1$s is the key of the subject, %2$d is workflow run ID.
-      ->withMessage(sprintf(__("Multiple subjects with key '%s' found, only one expected.", 'mailpoet'), $key));
+      ->withMessage(
+        sprintf(__("Multiple subjects with key '%1\$s' found for workflow run with ID '%2\$d', only one expected.", 'mailpoet'), $key, $workflowRunId)
+      );
   }
 
   public static function workflowStructureModificationNotSupported(): UnexpectedValueException {

mailpoet/lib/Automation/Engine/Workflows/Action.php

@@ -3,13 +3,11 @@
 namespace MailPoet\Automation\Engine\Workflows;
 
 use MailPoet\Automation\Engine\Data\Step as StepData;
-use MailPoet\Automation\Engine\Data\SubjectEntry;
+use MailPoet\Automation\Engine\Data\StepRunArgs;
 use MailPoet\Automation\Engine\Data\Workflow;
-use MailPoet\Automation\Engine\Data\WorkflowRun;
 
 interface Action extends Step {
   public function isValid(array $subjects, StepData $step, Workflow $workflow): bool;
 
-  /** @var SubjectEntry[] $subjectEntries */
+  public function run(StepRunArgs $args): void;
-  public function run(Workflow $workflow, WorkflowRun $workflowRun, StepData $step, array $subjectEntries): void;
 }