Improved static analysis for proxied workflows and activities

src/Activity.php

@@ -95,11 +95,11 @@ public static function hasHeartbeatDetails(): bool
      *
      * This method retrieves the payload that was passed into the last call of the {@see Activity::heartbeat()} method.
      *
-     * @param null|mixed $type
+     * @param mixed|null $type
      * @psalm-param TType $type
      * @throws OutOfContextException in the absence of the activity execution context.
      */
-    public static function getHeartbeatDetails($type = null): mixed
+    public static function getHeartbeatDetails(mixed $type = null): mixed
     {
         $context = self::getCurrentContext();
 
@@ -158,7 +158,7 @@ public static function doNotCompleteOnReturn(): void
      *
      * @throws OutOfContextException in the absence of the activity execution context.
      */
-    public static function heartbeat($details): void
+    public static function heartbeat(mixed $details): void
     {
         $context = self::getCurrentContext();
 

src/Client/Update/UpdateHandle.php

@@ -20,6 +20,7 @@
 /**
  * UpdateHandle is a handle to an update workflow execution request that can be used to get the
  * status of that update request.
+ * @template ReturnType
  */
 final class UpdateHandle
 {
@@ -69,6 +70,7 @@ public function hasResult(): bool
      *
      * @throws WorkflowUpdateException
      * @throws WorkflowUpdateRPCTimeoutOrCanceledException
+     * @return ReturnType
      */
     public function getResult(int|float|null $timeout = null): mixed
     {

src/Client/WorkflowClientInterface.php

@@ -20,6 +20,7 @@
 use Temporal\Client\Update\UpdateOptions;
 use Temporal\Client\Workflow\CountWorkflowExecutions;
 use Temporal\Client\Workflow\WorkflowExecutionHistory;
+use Temporal\Internal\Client\WorkflowProxy;
 use Temporal\Workflow\WorkflowExecution;
 use Temporal\Workflow\WorkflowExecutionInfo as WorkflowExecutionInfoDto;
 use Temporal\Workflow\WorkflowRunInterface;
@@ -91,9 +92,9 @@ public function updateWithStart(
      * IMPORTANT! Stub is per workflow instance. So new stub should be created
      * for each new one.
      *
-     * @psalm-template T of object
+     * @template T of object
      * @param class-string<T> $class
-     * @return T
+     * @return WorkflowProxy<T>
      */
     public function newWorkflowStub(
         string $class,
@@ -120,10 +121,10 @@ public function newUntypedWorkflowStub(
     /**
      * Returns workflow stub associated with running workflow.
      *
-     * @psalm-template T of object
+     * @template T of object
      * @param class-string<T> $class
      * @param non-empty-string $workflowID
-     * @return T
+     * @return WorkflowProxy<T>
      */
     public function newRunningWorkflowStub(
         string $class,

src/Client/WorkflowStubInterface.php

@@ -29,6 +29,8 @@
  *
  * It can be used to start, signal, query, wait for completion and cancel a workflow
  * execution. Created through {@see WorkflowClient::newUntypedWorkflowStub()}.
+ * @template ReturnType
+ * @extends WorkflowRunInterface<ReturnType>
  */
 interface WorkflowStubInterface extends WorkflowRunInterface
 {

src/Internal/Client/WorkflowProxy.php

@@ -24,6 +24,7 @@
 
 /**
  * @template-covariant T of object
+ * @mixin T
  * @internal
  */
 final class WorkflowProxy extends Proxy

src/Internal/Client/WorkflowRun.php

@@ -17,6 +17,10 @@
 use Temporal\Workflow\WorkflowExecution;
 use Temporal\Workflow\WorkflowRunInterface;
 
+/**
+ * @template ReturnType
+ * @implements WorkflowRunInterface<ReturnType>
+ */
 final class WorkflowRun implements WorkflowRunInterface
 {
     /**

src/Internal/Client/WorkflowStub.php

@@ -73,6 +73,10 @@
 use Temporal\Internal\Mapper\WorkflowExecutionInfoMapper;
 use Temporal\Workflow\WorkflowExecution;
 
+/**
+ * @template ReturnType
+ * @implements WorkflowStubInterface<ReturnType>
+ */
 final class WorkflowStub implements WorkflowStubInterface, HeaderCarrier
 {
     private const ERROR_WORKFLOW_NOT_STARTED = 'Method "%s" cannot be called because the workflow has not been started';

src/Internal/Declaration/Reader/Reader.php

@@ -14,7 +14,7 @@
 use Spiral\Attributes\ReaderInterface;
 
 /**
- * @psalm-template T of object
+ * @template T of object
  */
 abstract class Reader
 {

src/Internal/Workflow/ActivityProxy.php

@@ -24,6 +24,10 @@
 use Temporal\Internal\Transport\CompletableResultInterface;
 use Temporal\Workflow\WorkflowContextInterface;
 
+/**
+ * @template-covariant T of object
+ * @mixin T
+ */
 final class ActivityProxy extends Proxy
 {
     /**
@@ -42,6 +46,7 @@ final class ActivityProxy extends Proxy
     private WorkflowContextInterface $ctx;
 
     /**
+     * @param class-string<T> $class
      * @param array<ActivityPrototype> $activities
      * @param Pipeline<WorkflowOutboundCallsInterceptor, PromiseInterface> $callsInterceptor
      */

src/Internal/Workflow/ChildWorkflowProxy.php

@@ -20,6 +20,11 @@
 use Temporal\Workflow\ChildWorkflowStubInterface;
 use Temporal\Workflow\WorkflowContextInterface;
 
+/**
+ * @template-covariant T of object
+ * @mixin T
+ * @internal
+ */
 final class ChildWorkflowProxy extends Proxy
 {
     private const ERROR_UNDEFINED_WORKFLOW_METHOD =

src/Internal/Workflow/ContinueAsNewProxy.php

@@ -17,7 +17,12 @@
 use Temporal\Workflow\ContinueAsNewOptions;
 use Temporal\Workflow\WorkflowContextInterface;
 
-class ContinueAsNewProxy extends Proxy
+/**
+ * @template-covariant T of object
+ * @mixin T
+ * @internal
+ */
+final class ContinueAsNewProxy extends Proxy
 {
     /**
      * @var string

src/Internal/Workflow/ExternalWorkflowProxy.php

@@ -16,7 +16,12 @@
 use Temporal\Internal\Support\Reflection;
 use Temporal\Workflow\ExternalWorkflowStubInterface;
 
-class ExternalWorkflowProxy extends Proxy
+/**
+ * @template-covariant T of object
+ * @mixin T
+ * @internal
+ */
+final class ExternalWorkflowProxy extends Proxy
 {
     /**
      * @var string

src/Internal/Workflow/Proxy.php

@@ -18,7 +18,7 @@ abstract class Proxy
     abstract public function __call(string $method, array $args);
 
     /**
-     * @psalm-template T of Prototype
+     * @template T of Prototype
      *
      * @param array<T> $prototypes
      * @return T|null

src/Internal/Workflow/WorkflowContext.php

@@ -443,6 +443,11 @@ public function newUntypedActivityStub(
         return new ActivityStub($this->services->marshaller, $options, $this->getHeader());
     }
 
+    /**
+     * @template T of object
+     * @param class-string<T> $class
+     * @return ActivityProxy<T>
+     */
     public function newActivityStub(
         string $class,
         ?ActivityOptionsInterface $options = null,

src/Workflow.php

@@ -23,6 +23,10 @@
 use Temporal\Exception\Failure\CanceledFailure;
 use Temporal\Exception\OutOfContextException;
 use Temporal\Internal\Support\Facade;
+use Temporal\Internal\Workflow\ActivityProxy;
+use Temporal\Internal\Workflow\ChildWorkflowProxy;
+use Temporal\Internal\Workflow\ContinueAsNewProxy;
+use Temporal\Internal\Workflow\ExternalWorkflowProxy;
 use Temporal\Workflow\ActivityStubInterface;
 use Temporal\Workflow\CancellationScopeInterface;
 use Temporal\Workflow\ChildWorkflowOptions;
@@ -675,10 +679,10 @@ public static function continueAsNew(
      *  }
      * ```
      *
-     * @psalm-template T of object
+     * @template T of object
      *
      * @param class-string<T> $class
-     * @return T
+     * @return ContinueAsNewProxy<T>
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
     public static function newContinueAsNewStub(string $class, ?ContinueAsNewOptions $options = null): object
@@ -778,11 +782,11 @@ public static function executeChildWorkflow(
      *  }
      * ```
      *
-     * @psalm-template T of object
+     * @template T of object
      *
      * @param class-string<T> $class
      *
-     * @return T
+     * @return ChildWorkflowProxy<T>
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
     public static function newChildWorkflowStub(
@@ -858,10 +862,10 @@ public static function newUntypedChildWorkflowStub(
      *  }
      * ```
      *
-     * @psalm-template T of object
+     * @template T of object
      *
      * @param class-string<T> $class
-     * @return T
+     * @return ExternalWorkflowProxy<T>
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
     public static function newExternalWorkflowStub(string $class, WorkflowExecution $execution): object
@@ -966,11 +970,11 @@ public static function executeActivity(
      *  }
      * ```
      *
-     * @psalm-template T of object
+     * @template T of object
      *
      * @param class-string<T> $class
      *
-     * @return T
+     * @return ActivityProxy<T>
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
     public static function newActivityStub(

src/Workflow/WorkflowContextInterface.php

@@ -20,6 +20,10 @@
 use Temporal\DataConverter\Type;
 use Temporal\DataConverter\ValuesInterface;
 use Temporal\Internal\Support\DateInterval;
+use Temporal\Internal\Workflow\ActivityProxy;
+use Temporal\Internal\Workflow\ChildWorkflowProxy;
+use Temporal\Internal\Workflow\ContinueAsNewProxy;
+use Temporal\Internal\Workflow\ExternalWorkflowProxy;
 use Temporal\Worker\Transport\Command\RequestInterface;
 use Temporal\Worker\Environment\EnvironmentInterface;
 use Temporal\Workflow;
@@ -190,9 +194,9 @@ public function continueAsNew(
      *
      * @see Workflow::newContinueAsNewStub()
      *
-     * @psalm-template T of object
+     * @template T of object
      * @param class-string<T> $class
-     * @return T
+     * @return ContinueAsNewProxy<T>
      */
     public function newContinueAsNewStub(string $class, ?ContinueAsNewOptions $options = null): object;
 
@@ -215,10 +219,10 @@ public function executeChildWorkflow(
      *
      * @see Workflow::newChildWorkflowStub()
      *
-     * @psalm-template T of object
+     * @template T of object
      * @param class-string<T> $class
      *
-     * @return T
+     * @return ChildWorkflowProxy<T>
      */
     public function newChildWorkflowStub(
         string $class,
@@ -241,9 +245,9 @@ public function newUntypedChildWorkflowStub(
      *
      * @see Workflow::newExternalWorkflowStub()
      *
-     * @psalm-template T of object
+     * @template T of object
      * @param class-string<T> $class
-     * @return T
+     * @return ExternalWorkflowProxy<T>
      */
     public function newExternalWorkflowStub(string $class, WorkflowExecution $execution): object;
 
@@ -278,10 +282,10 @@ public function executeActivity(
      *
      * @see Workflow::newActivityStub()
      *
-     * @psalm-template T of object
+     * @template T of object
      * @param class-string<T> $class
      *
-     * @return T
+     * @return ActivityProxy<T>
      */
     public function newActivityStub(
         string $class,

src/Workflow/WorkflowRunInterface.php

@@ -17,6 +17,7 @@
 
 /**
  * Represents a running workflow execution. Can be used to wait for the completion result or error.
+ * @template ReturnType
  */
 interface WorkflowRunInterface
 {
@@ -41,6 +42,7 @@ public function getExecution(): WorkflowExecution;
      * @param string|\ReflectionClass|\ReflectionType|Type|null $type
      * @param int|null $timeout Timeout in seconds. Infinite by the default.
      * @throws WorkflowFailedException
+     * @return ReturnType
      *
      * @see DateInterval
      */

tests/Fixtures/src/Workflow/GeneratorWorkflow.php

@@ -40,11 +40,13 @@ public function handler(
     }
 
     /**
-     * @param ActivityProxy|SimpleActivity $simple
+     * @param ActivityProxy<SimpleActivity> $simple
      */
     private function doSomething(ActivityProxy $simple, string $input): \Generator
     {
-        $input === 'error' and throw new \Exception('error from generator');
+        if ($input === 'error') {
+            throw new \Exception('error from generator');
+        }
 
         if ($input === 'failure') {
             yield $simple->fail();