feat: Add WorkflowContextInterface::getInstance();

Throw OutOfContextException if Workflow or Activity facades are called from a wrong context;
Fix psalm issues;

Author: roxblnfk

psalm-baseline.xml

@@ -342,34 +342,11 @@
     <InvalidArgument>
       <code><![CDATA[$message->getDetails()]]></code>
     </InvalidArgument>
-    <MismatchingDocblockParamType>
-      <code><![CDATA[\ArrayAccess<int, Any>&RepeatedField]]></code>
-    </MismatchingDocblockParamType>
-    <MismatchingDocblockPropertyType>
-      <code><![CDATA[\ArrayAccess<int, Any>&RepeatedField]]></code>
-    </MismatchingDocblockPropertyType>
-    <MismatchingDocblockReturnType>
-      <code><![CDATA[\ArrayAccess<int, Any>&RepeatedField]]></code>
-    </MismatchingDocblockReturnType>
   </file>
   <file src="src/Exception/Client/ServiceClientException.php">
     <ImplementedReturnTypeMismatch>
       <code><![CDATA[RepeatedField]]></code>
     </ImplementedReturnTypeMismatch>
-    <InvalidReturnStatement>
-      <code><![CDATA[$this->status->getDetails()]]></code>
-    </InvalidReturnStatement>
-    <InvalidReturnType>
-      <code><![CDATA[RepeatedField]]></code>
-    </InvalidReturnType>
-  </file>
-  <file src="src/Exception/Client/UnpackDetailsTrait.php">
-    <RawObjectIteration>
-      <code><![CDATA[$details]]></code>
-    </RawObjectIteration>
-    <UndefinedInterfaceMethod>
-      <code><![CDATA[count]]></code>
-    </UndefinedInterfaceMethod>
   </file>
   <file src="src/Exception/Client/WorkflowException.php">
     <UnsafeInstantiation>
@@ -827,9 +804,6 @@
     <NullableReturnStatement>
       <code><![CDATA[$mapper]]></code>
     </NullableReturnStatement>
-    <PossibleRawObjectIteration>
-      <code><![CDATA[$value]]></code>
-    </PossibleRawObjectIteration>
     <PossiblyNullArgument>
       <code><![CDATA[$metadata->getDetails()]]></code>
       <code><![CDATA[$metadata->getSummary()]]></code>
@@ -997,13 +971,6 @@
       <code><![CDATA[$reflection->getName()]]></code>
     </PropertyTypeCoercion>
   </file>
-  <file src="src/Internal/Support/Facade.php">
-    <InvalidDocblock>
-      <code><![CDATA[object<T>|null]]></code>
-      <code><![CDATA[private static ?object $ctx = null;]]></code>
-      <code><![CDATA[public static function getCurrentContext(): object]]></code>
-    </InvalidDocblock>
-  </file>
   <file src="src/Internal/Support/Inheritance.php">
     <PossiblyFalseArgument>
       <code><![CDATA[$implements]]></code>
@@ -1513,16 +1480,9 @@
     </UnsafeInstantiation>
   </file>
   <file src="src/Workflow.php">
-    <InvalidReturnStatement>
-      <code><![CDATA[self::getCurrentContext()->newActivityStub($class, $options)]]></code>
-      <code><![CDATA[self::getCurrentContext()->registerQuery($queryType, $handler, $description)]]></code>
-      <code><![CDATA[self::getCurrentContext()->registerSignal($name, $handler, $description)]]></code>
-    </InvalidReturnStatement>
-    <InvalidReturnType>
-      <code><![CDATA[ScopedContextInterface]]></code>
-      <code><![CDATA[ScopedContextInterface]]></code>
-      <code><![CDATA[T]]></code>
-    </InvalidReturnType>
+    <UndefinedInterfaceMethod>
+      <code><![CDATA[getUpdateContext]]></code>
+    </UndefinedInterfaceMethod>
   </file>
   <file src="src/Workflow/ChildWorkflowOptions.php">
     <PossiblyNullReference>

src/Activity.php

@@ -17,21 +17,32 @@
 use Temporal\DataConverter\Type;
 use Temporal\DataConverter\ValuesInterface;
 use Temporal\Exception\OutOfContextException;
+use Temporal\Internal\Activity\ActivityContext;
 use Temporal\Internal\Support\Facade;
 
-/**
- * @template-extends Facade<ActivityContextInterface>
- */
 final class Activity extends Facade
 {
+    /**
+     * Get the current Activity context.
+     * @throws OutOfContextException
+     */
+    public static function getCurrentContext(): ActivityContextInterface
+    {
+        $ctx = parent::getCurrentContext();
+        /** @var ActivityContext $ctx */
+        $ctx::class === ActivityContext::class or throw new OutOfContextException(
+            'The Activity facade can only be used in the context of an activity execution.',
+        );
+        return $ctx;
+    }
+
     /**
      * Returns information about current activity execution.
      *
      * @throws OutOfContextException in the absence of the activity execution context.
      */
     public static function getInfo(): ActivityInfo
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->getInfo();
@@ -57,7 +68,6 @@ public static function getInfo(): ActivityInfo
      */
     public static function getInput(): ValuesInterface
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->getInput();
@@ -72,7 +82,6 @@ public static function getInput(): ValuesInterface
      */
     public static function hasHeartbeatDetails(): bool
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->hasHeartbeatDetails();
@@ -88,7 +97,6 @@ public static function hasHeartbeatDetails(): bool
      */
     public static function getHeartbeatDetails($type = null): mixed
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->getLastHeartbeatDetails($type);
@@ -101,7 +109,6 @@ public static function getHeartbeatDetails($type = null): mixed
      */
     public static function getCancellationDetails(): ?ActivityCancellationDetails
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->getCancellationDetails();
@@ -118,7 +125,6 @@ public static function getCancellationDetails(): ?ActivityCancellationDetails
      */
     public static function doNotCompleteOnReturn(): void
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         $context->doNotCompleteOnReturn();
@@ -150,7 +156,6 @@ public static function doNotCompleteOnReturn(): void
      */
     public static function heartbeat($details): void
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         $context->heartbeat($details);
@@ -161,7 +166,6 @@ public static function heartbeat($details): void
      */
     public static function getInstance(): object
     {
-        /** @var ActivityContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->getInstance();

src/Internal/Support/Facade.php

@@ -13,9 +13,6 @@
 
 use Temporal\Exception\OutOfContextException;
 
-/**
- * @template T of object
- */
 abstract class Facade
 {
     /**
@@ -26,9 +23,6 @@ abstract class Facade
         'from the currently running process'
     ;
 
-    /**
-     * @var object<T>|null
-     */
     private static ?object $ctx = null;
 
     /**
@@ -40,7 +34,6 @@ private function __construct()
     }
 
     /**
-     * @param object<T>|null $ctx
      * @internal
      */
     public static function setCurrentContext(?object $ctx): void
@@ -49,7 +42,6 @@ public static function setCurrentContext(?object $ctx): void
     }
 
     /**
-     * @return object<T>
      * @throws OutOfContextException
      */
     public static function getCurrentContext(): object

src/Internal/Transport/Router/InvokeActivity.php

@@ -101,6 +101,7 @@ static function (ActivityInput $input) use ($handler, $context): mixed {
                     'handleActivityInbound',
                 )(new ActivityInput($context->getInput(), $context->getHeader()));
 
+            /** @var ActivityContext $context */
             $context = Activity::getCurrentContext();
             if ($context->isDoNotCompleteOnReturn()) {
                 $resolver->reject(DoNotCompleteOnResultException::create());

src/Workflow.php

@@ -45,18 +45,28 @@
  *
  * This is main class you can use in your workflow code.
  *
- * @method static ScopeContext getCurrentContext() Get current workflow context.
- *
  * @psalm-import-type TypeEnum from Type
  * @psalm-import-type DateIntervalValue from DateInterval
  * @see DateInterval
- *
- * @template-extends Facade<ScopedContextInterface>
  */
 final class Workflow extends Facade
 {
     public const DEFAULT_VERSION = -1;
 
+    /**
+     * Get the current Workflow context.
+     * @throws OutOfContextException
+     */
+    public static function getCurrentContext(): ScopedContextInterface
+    {
+        $ctx = parent::getCurrentContext();
+        /** @var ScopeContext $ctx */
+        $ctx::class === ScopeContext::class or throw new OutOfContextException(
+            'The Workflow facade can be used only inside workflow code.',
+        );
+        return $ctx;
+    }
+
     /**
      * Returns current datetime.
      *
@@ -995,7 +1005,6 @@ public static function getStackTrace(): string
      */
     public static function allHandlersFinished(): bool
     {
-        /** @var ScopedContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->allHandlersFinished();
@@ -1081,7 +1090,6 @@ public static function upsertTypedSearchAttributes(SearchAttributeUpdate ...$upd
      */
     public static function uuid(): PromiseInterface
     {
-        /** @var ScopedContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->uuid();
@@ -1094,7 +1102,6 @@ public static function uuid(): PromiseInterface
      */
     public static function uuid4(): PromiseInterface
     {
-        /** @var ScopedContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->uuid4();
@@ -1111,7 +1118,6 @@ public static function uuid4(): PromiseInterface
      */
     public static function uuid7(?\DateTimeInterface $dateTime = null): PromiseInterface
     {
-        /** @var ScopedContextInterface $context */
         $context = self::getCurrentContext();
 
         return $context->uuid7($dateTime);

src/Workflow/WorkflowContextInterface.php

@@ -19,6 +19,7 @@
 use Temporal\Common\SearchAttributes\SearchAttributeUpdate;
 use Temporal\DataConverter\Type;
 use Temporal\DataConverter\ValuesInterface;
+use Temporal\Exception\OutOfContextException;
 use Temporal\Internal\Support\DateInterval;
 use Temporal\Worker\Transport\Command\RequestInterface;
 use Temporal\Worker\Environment\EnvironmentInterface;
@@ -440,4 +441,9 @@ public function uuid7(?\DateTimeInterface $dateTime = null): PromiseInterface;
      * Logs in replay mode are omitted unless {@see WorkerOptions::$enableLoggingInReplay} is set to true.
      */
     public function getLogger(): LoggerInterface;
+
+    /**
+     * Get the currently running Workflow instance.
+     */
+    public function getInstance(): object;
 }