Merged container for nested workflows

Author: wol-soft

README.md

@@ -300,26 +300,32 @@ public function warning(string $message, ?Exception $exception = null): void;
 If some of your steps become more complex you may want to have a look into the `NestedWorkflow` wrapper which allows you to use a second workflow as a step of your workflow:
 
 ```php
+$parentWorkflowContainer = (new \PHPWorkflow\State\WorkflowContainer())->set('parent-data', 'Hello');
+$nestedWorkflowContainer = (new \PHPWorkflow\State\WorkflowContainer())->set('nested-data', 'World');
+
 $workflowResult = (new \PHPWorkflow\Workflow('AddSongToPlaylist'))
     ->validate(new CurrentUserIsAllowedToEditPlaylistValidator())
     ->before(new \PHPWorkflow\Step\NestedWorkflow(
         (new \PHPWorkflow\Workflow('AcceptOpenSuggestions'))
             ->validate(new PlaylistAcceptsSuggestionsValidator())
             ->before(new LoadOpenSuggestions())
             ->process(new AcceptOpenSuggestions())
-            ->onSuccess(new NotifySuggestor())
+            ->onSuccess(new NotifySuggestor()),
+        $nestedWorkflowContainer,
     ))
     ->process(new AddSongToPlaylist())
     ->onSuccess(new NotifySubscribers())
-    ->executeWorkflow();
+    ->executeWorkflow($parentWorkflowContainer);
 ```
 
 Each nested workflow must be executable (contain at least one **Process** step).
 
 The debug log of your nested workflow will be embedded in the debug log of your main workflow.
 
-As you can see in the example you can't inject a **WorkflowContainer** into the nested workflow.
-The nested workflow has access to your main workflow container and can read or add data to the container.
+As you can see in the example you can inject a dedicated **WorkflowContainer** into the nested workflow.
+The nested workflow will gain access to a merged **WorkflowContainer** which provides all data and methods of your main workflow container and your nested container.
+If you add additional data to the merged container the data will be present in your main workflow container after the nested workflow execution has been completed.
+For example your implementations of the steps used in the nested workflow will have access to the keys `nested-data` and `parent-data`.
 
 ## Error handling, logging and debugging
 

src/State/NestedContainer.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPWorkflow\State;
+
+class NestedContainer extends WorkflowContainer
+{
+    private WorkflowContainer $parentContainer;
+    private ?WorkflowContainer $container;
+
+    public function __construct(WorkflowContainer $parentContainer, ?WorkflowContainer $container)
+    {
+        $this->parentContainer = $parentContainer;
+        $this->container = $container;
+    }
+
+    public function get(string $key)
+    {
+        if (!$this->container) {
+            return $this->parentContainer->get($key);
+        }
+
+        return $this->container->get($key) ?? $this->parentContainer->get($key);
+    }
+
+    public function set(string $key, $value): WorkflowContainer
+    {
+        if ($this->container) {
+            $this->container->set($key, $value);
+        }
+
+        $this->parentContainer->set($key, $value);
+
+        return $this;
+    }
+
+    public function __call(string $name, array $arguments)
+    {
+        if ($this->container && method_exists($this->container, $name)) {
+            return $this->container->{$name}(...$arguments);
+        }
+
+        // don't check if the method exists to trigger an error if the method neither exists in $container nor in
+        // $parentContainer
+        return $this->parentContainer->{$name}(...$arguments);
+    }
+}

src/Step/NestedWorkflow.php

@@ -6,16 +6,19 @@
 
 use PHPWorkflow\Exception\WorkflowException;
 use PHPWorkflow\ExecutableWorkflow;
+use PHPWorkflow\State\NestedContainer;
 use PHPWorkflow\State\WorkflowContainer;
 use PHPWorkflow\WorkflowControl;
 
 class NestedWorkflow implements WorkflowStep
 {
     private ExecutableWorkflow $nestedWorkflow;
+    private ?WorkflowContainer $container;
 
-    public function __construct(ExecutableWorkflow $nestedWorkflow)
+    public function __construct(ExecutableWorkflow $nestedWorkflow, ?WorkflowContainer $container = null)
     {
         $this->nestedWorkflow = $nestedWorkflow;
+        $this->container = $container;
     }
 
     public function getDescription(): string
@@ -27,7 +30,7 @@ public function run(WorkflowControl $control, WorkflowContainer $container)
     {
         try {
             $workflowResult = $this->nestedWorkflow->executeWorkflow(
-                $container,
+                new NestedContainer($container, $this->container),
                 // TODO: array unpacking via named arguments when dropping PHP7 support
                 $container->get('__internalExecutionConfiguration')['throwOnFailure'],
             );

tests/WorkflowTest.php

@@ -9,6 +9,7 @@
 use PHPWorkflow\Exception\WorkflowControl\FailWorkflowException;
 use PHPWorkflow\Exception\WorkflowException;
 use PHPWorkflow\Exception\WorkflowValidationException;
+use PHPWorkflow\Middleware\ProfileStep;
 use PHPWorkflow\State\WorkflowContainer;
 use PHPWorkflow\Step\NestedWorkflow;
 use PHPWorkflow\Workflow;
@@ -572,14 +573,18 @@ public function testNestedWorkflow(): void
                     ))
                     ->process($this->setupStep(
                         'nested-process-test',
-                        fn (WorkflowControl $control, WorkflowContainer $container) =>
-                            $control->attachStepInfo($container->get('testdata')),
+                        function (WorkflowControl $control, WorkflowContainer $container) {
+                            $control->warning('nested-warning-message');
+                            $control->attachStepInfo($container->get('testdata'));
+                        },
                     ))
             ))
             ->process($this->setupStep(
                 'process-test',
-                fn (WorkflowControl $control, WorkflowContainer $container) =>
-                    $control->attachStepInfo($container->get('additional-data')),
+                function (WorkflowControl $control, WorkflowContainer $container) {
+                    $control->warning('warning-message');
+                    $control->attachStepInfo($container->get('additional-data'));
+                },
             ))
             ->executeWorkflow($container);
 
@@ -588,24 +593,29 @@ public function testNestedWorkflow(): void
             <<<DEBUG
             Process log for workflow 'test':
             Before:
-              - Execute nested workflow: ok
+              - Execute nested workflow: ok (1 warning)
                 - Process log for workflow 'nested-test':
                   Before:
                     - nested-before-test: ok
                   Process:
-                    - nested-process-test: ok
+                    - nested-process-test: ok (1 warning)
                       - Hello World
 
                   Summary:
                     - Workflow execution: ok
                       - Execution time: *
+                      - Got 1 warning during the execution:
+                          Process: nested-warning-message
             Process:
-              - process-test: ok
+              - process-test: ok (1 warning)
                 - from-nested
 
             Summary:
               - Workflow execution: ok
                 - Execution time: *
+                - Got 2 warnings during the execution:
+                    Before: Nested workflow 'nested-test' emitted 1 warning
+                    Process: warning-message
             DEBUG,
             $result,
         );
@@ -649,4 +659,125 @@ function () {
             $result,
         );
     }
+
+    public function testNestedWorkflowHasMergedContainer(): void
+    {
+        $parentContainer = new class () extends WorkflowContainer {
+            public function getParentData(): string
+            {
+                return 'parent-data';
+            }
+        };
+        $parentContainer->set('set-parent', 'set-parent-data');
+
+        $nestedContainer = new class () extends WorkflowContainer {
+            public function getNestedData(): string
+            {
+                return 'nested-data';
+            }
+        };
+        $nestedContainer->set('set-nested', 'set-nested-data');
+        
+
+        $result = (new Workflow('test'))
+            ->before(new NestedWorkflow(
+                (new Workflow('nested-test'))
+                    ->before($this->setupStep(
+                        'nested-before-test',
+                        function (WorkflowControl $control, WorkflowContainer $container) {
+                            $control->attachStepInfo($container->getParentData());
+                            $control->attachStepInfo($container->getNestedData());
+                            $control->attachStepInfo($container->get('set-parent'));
+                            $control->attachStepInfo($container->get('set-nested'));
+
+                            $container->set('additional-data', 'from-nested');
+                        },
+                    ))
+                    ->process($this->setupStep(
+                        'nested-process-test',
+                        function (WorkflowControl $control, WorkflowContainer $container) {
+                            $control->attachStepInfo($container->get('additional-data'));
+                        },
+                    )),
+                    $nestedContainer,
+            ))
+            ->process($this->setupStep(
+                'process-test',
+                function (WorkflowControl $control, WorkflowContainer $container) {
+                    $control->attachStepInfo($container->get('additional-data'));
+                    $control->attachStepInfo($container->get('set-parent'));
+                    $control->attachStepInfo(var_export($container->get('set-nested'), true));
+                },
+            ))
+            ->executeWorkflow($parentContainer);
+
+        $this->assertTrue($result->success());
+        $this->assertDebugLog(
+            <<<DEBUG
+            Process log for workflow 'test':
+            Before:
+              - Execute nested workflow: ok
+                - Process log for workflow 'nested-test':
+                  Before:
+                    - nested-before-test: ok
+                      - parent-data
+                      - nested-data
+                      - set-parent-data
+                      - set-nested-data
+                  Process:
+                    - nested-process-test: ok
+                      - from-nested
+
+                  Summary:
+                    - Workflow execution: ok
+                      - Execution time: *
+            Process:
+              - process-test: ok
+                - from-nested
+                - set-parent-data
+                - NULL
+
+            Summary:
+              - Workflow execution: ok
+                - Execution time: *
+            DEBUG,
+            $result,
+        );
+
+        // test data is accessible via main container
+        $this->assertSame('from-nested', $result->getContainer()->get('additional-data'));
+        $this->assertSame('set-parent-data', $result->getContainer()->get('set-parent'));
+        $this->assertNull($result->getContainer()->get('set-nested'));
+    }
+
+    public function testProfilingMiddleware(): void
+    {
+        $result = (new Workflow('test', new ProfileStep()))
+            ->before($this->setupEmptyStep('before-test'))
+            ->process($this->setupEmptyStep('process-test'))
+            ->onSuccess($this->setupEmptyStep('success-test'))
+            ->executeWorkflow();
+
+        $this->assertTrue($result->success());
+
+        $this->assertDebugLog(
+            <<<DEBUG
+            Process log for workflow 'test':
+            Before:
+              - before-test: ok
+                - Step execution time: *
+            Process:
+              - process-test: ok
+                - Step execution time: *
+            On Success:
+              - success-test: ok
+                - Step execution time: *
+
+            Summary:
+              - Workflow execution: ok
+                - Execution time: *
+            DEBUG,
+            $result,
+        );
+    }
 }