From 1847f723ff5ece0320dccfc30312da387c032b96 Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Fri, 12 Apr 2024 17:23:23 +0400
Subject: [PATCH] Add `WorkflowClientInterface::newWorkflowProxy()` and
 `WorkflowClientInterface::newRunningWorkflowProxy()`; add `$proxy` parameter

---
 src/Client/WorkflowClient.php          | 23 +++++++++-
 src/Client/WorkflowClientInterface.php | 62 +++++++++++++++++++++++---
 2 files changed, 78 insertions(+), 7 deletions(-)

diff --git a/src/Client/WorkflowClient.php b/src/Client/WorkflowClient.php
index 3af0f616b..b49b777c8 100644
--- a/src/Client/WorkflowClient.php
+++ b/src/Client/WorkflowClient.php
@@ -233,7 +233,15 @@ public function startWithSignal(
     public function newWorkflowStub(
         string $class,
         WorkflowOptions $options = null,
+        bool $proxy = true,
     ): object {
+        $proxy and \trigger_error(
+            'Use `newRunningWorkflowProxy()` to create a Workflow proxy instance.',
+            \E_USER_DEPRECATED,
+        );
+
+        // todo create stub or proxy
+
         $workflow = $this->reader->fromClass($class);
 
         return new WorkflowProxy(
@@ -265,8 +273,19 @@ public function newUntypedWorkflowStub(
     /**
      * {@inheritDoc}
      */
-    public function newRunningWorkflowStub(string $class, string $workflowID, ?string $runID = null): object
-    {
+    public function newRunningWorkflowStub(
+        string $class,
+        string $workflowID,
+        ?string $runID = null,
+        bool $proxy = true,
+    ): object {
+        $proxy and \trigger_error(
+            'Use `newRunningWorkflowProxy()` to create a Workflow proxy instance.',
+            \E_USER_DEPRECATED,
+        );
+
+        // todo create stub or proxy
+
         $workflow = $this->reader->fromClass($class);
 
         return new WorkflowProxy(
diff --git a/src/Client/WorkflowClientInterface.php b/src/Client/WorkflowClientInterface.php
index 04abb139d..d48c4598c 100644
--- a/src/Client/WorkflowClientInterface.php
+++ b/src/Client/WorkflowClientInterface.php
@@ -67,16 +67,45 @@ public function startWithSignal(
      * @psalm-template T of object
      * @param class-string<T> $class
      * @param WorkflowOptions|null $options
-     * @return T
+     * @param bool $proxy If set to true, the method will return as the same as {@see self::newWorkflowProxy()}.
+     *        The parameter has {@see true} value by default to keep backward compatibility.
+     *        If you want to get a stub instance, set it to {@see false}, otherwise use {@see self::newWorkflowStub()}.
+     *        This parameter will be removed from the interface in the next major release and the method will
+     *        return exactly {@see WorkflowStubInterface}.
+     * @return ($poxy is false ? WorkflowStubInterface : T)
      */
     public function newWorkflowStub(
         string $class,
         WorkflowOptions $options = null,
+        bool $proxy = true,
+    ): object;
+
+    /**
+     * Creates a Workflow client proxy that can be used to start a single workflow execution.
+     * The proxy doesn't implement passed Workflow interface, but it will forward all the interface calls to the
+     * Workflow instance.
+     *
+     * The first call must be to a method annotated with {@see WorkflowMethod}.
+     * After related Workflow is started, the proxy can be also used to send signals, queries or updates to it.
+     *
+     * Use WorkflowClient->start($workflowProxy, ...$args) to start workflow asynchronously.
+     *
+     * IMPORTANT!
+     * There must be only one proxy per a workflow instance.
+     *
+     * @psalm-template T of object
+     * @param class-string<T> $class
+     * @param WorkflowOptions|null $options
+     * @return T
+     */
+    public function newWorkflowProxy(
+        string $class,
+        WorkflowOptions $options = null,
     ): object;
 
     /**
-     * Creates workflow untyped client stub that can be used to start a single
-     * workflow execution. After workflow is started it can be also used to send
+     * Creates Workflow untyped Client stub that can be used to start a single
+     * Workflow execution. After workflow is started it can be also used to send
      * signals or queries to it.
      *
      * Use WorkflowClient->start($workflowStub, ...$args) to start workflow asynchronously.
@@ -100,12 +129,35 @@ public function newUntypedWorkflowStub(
      * @param class-string<T> $class
      * @param string $workflowID
      * @param string|null $runID
-     * @return T
+     * @param bool $proxy If set to true, the method will return as the same as {@see self::newWorkflowProxy()}.
+     *         The parameter has {@see true} value by default to keep backward compatibility.
+     *         If you want to get a stub instance, set it to {@see false}, otherwise use {@see self::newWorkflowStub()}.
+     *         This parameter will be removed from the interface in the next major release and set to {@see false} in
+     *         an implementation.
+     * @return ($poxy is false ? WorkflowStubInterface : T)
      */
     public function newRunningWorkflowStub(
         string $class,
         string $workflowID,
-        ?string $runID = null
+        ?string $runID = null,
+        bool $proxy = true,
+    ): object;
+
+    /**
+     * Returns Workflow proxy associated with running Workflow.
+     * The proxy doesn't implement passed Workflow interface, but it will forward all the interface calls to the
+     * Workflow instance.
+     *
+     * @psalm-template T of object
+     * @param class-string<T> $class
+     * @param string $workflowID
+     * @param string|null $runID
+     * @return T
+     */
+    public function newRunningWorkflowProxy(
+        string $class,
+        string $workflowID,
+        ?string $runID = null,
     ): object;
 
     /**