feat: introduce WorkflowVersioningBehavior attribute and enhance workflow versioning support

Author: roxblnfk

src/Internal/Declaration/Graph/ClassNode.php

@@ -58,7 +58,7 @@ public function count(): int
      * Get a method with all the declared classes.
      *
      * @param non-empty-string $name
-     * @return \Traversable<ClassNode, \ReflectionMethod>
+     * @return \Traversable<int, \Traversable<class-string, \ReflectionMethod>>
      * @throws \ReflectionException
      */
     public function getMethods(string $name, bool $reverse = true): \Traversable
@@ -190,6 +190,7 @@ private function getInheritance(): array
 
     /**
      * @param iterable<ClassNode> $classes
+     * @return list<array{class-string, \ReflectionMethod}>
      * @throws \ReflectionException
      */
     private function boxMethods(iterable $classes, string $name): array
@@ -205,6 +206,10 @@ private function boxMethods(iterable $classes, string $name): array
         return $result;
     }
 
+    /**
+     * @param array<array{class-string, \ReflectionMethod}> $boxed
+     * @return \Traversable<class-string, \ReflectionMethod>
+     */
     private function unboxMethods(array $boxed): \Traversable
     {
         $unpack = static function () use ($boxed) {

src/Internal/Declaration/Prototype/WorkflowPrototype.php

@@ -14,6 +14,7 @@
 use Temporal\Common\CronSchedule;
 use Temporal\Common\MethodRetry;
 use Temporal\Internal\Declaration\EntityNameValidator;
+use Temporal\Worker\Versioning\VersioningBehavior;
 use Temporal\Workflow\ReturnType;
 use Temporal\Workflow\WorkflowInit;
 
@@ -43,12 +44,14 @@ final class WorkflowPrototype extends Prototype
     private ?MethodRetry $methodRetry = null;
     private ?ReturnType $returnType = null;
     private bool $hasInitializer = false;
+    private VersioningBehavior $versioningBehavior;
 
     public function __construct(
         string $name,
         ?\ReflectionMethod $handler,
         \ReflectionClass $class,
     ) {
+        $this->versioningBehavior = VersioningBehavior::Unspecified;
         EntityNameValidator::validateWorkflow($name);
         parent::__construct($name, $handler, $class);
     }
@@ -96,6 +99,11 @@ public function setReturnType(?ReturnType $attribute): void
         $this->returnType = $attribute;
     }
 
+    public function setVersioningBehavior(VersioningBehavior $behavior): void
+    {
+        $this->versioningBehavior = $behavior;
+    }
+
     public function addQueryHandler(QueryDefinition $definition): void
     {
         EntityNameValidator::validateQueryMethod($definition->name);
@@ -156,4 +164,9 @@ public function getValidateUpdateHandlers(): array
     {
         return $this->updateValidators;
     }
+
+    public function getVersioningBehavior(): VersioningBehavior
+    {
+        return $this->versioningBehavior;
+    }
 }

src/Internal/Declaration/Reader/WorkflowReader.php

@@ -27,6 +27,7 @@
 use Temporal\Workflow\WorkflowInit;
 use Temporal\Workflow\WorkflowInterface;
 use Temporal\Workflow\WorkflowMethod;
+use Temporal\Workflow\WorkflowVersioningBehavior;
 
 /**
  * @template-extends Reader<WorkflowPrototype>
@@ -292,14 +293,16 @@ private function getAttributedMethod(ClassNode $graph, \ReflectionMethod $handle
     }
 
     /**
+     * Walk through the method hierarchy and build the prototype for the workflow method.
+     *
      * @throws \ReflectionException
      */
     private function getPrototype(ClassNode $graph, \ReflectionMethod $handler): ?WorkflowPrototype
     {
-        $cronSchedule = $previousRetry = $prototype = $returnType = null;
+        $cronSchedule = $previousRetry = $prototype = $returnType = $versionBehavior = null;
 
+        /** @var \Traversable<class-string, \ReflectionMethod> $group */
         foreach ($graph->getMethods($handler->getName()) as $group) {
-            //
             $contextualRetry = $previousRetry;
 
             foreach ($group as $method) {
@@ -326,6 +329,11 @@ private function getPrototype(ClassNode $graph, \ReflectionMethod $handler): ?Wo
                     ?? $returnType
                 ;
 
+                // Version Behavior
+                $versionBehavior = $this->reader->firstFunctionMetadata($method, WorkflowVersioningBehavior::class)
+                    ?? $versionBehavior
+                ;
+
                 //
                 // In the future, workflow methods are available only in
                 // those classes that contain the attribute:
@@ -347,27 +355,18 @@ private function getPrototype(ClassNode $graph, \ReflectionMethod $handler): ?Wo
                     }
                 }
 
-                // In case
+                // Skip if no interface found
                 if ($interface === null) {
                     continue;
                 }
 
                 \assert($context !== null);
-                if ($prototype === null) {
-                    $prototype = $this->findProto($handler, $method, $context, $graph->getReflection());
-                }
-
-                if ($prototype !== null && $retry !== null) {
-                    $prototype->setMethodRetry($retry);
-                }
-
-                if ($prototype !== null && $cronSchedule !== null) {
-                    $prototype->setCronSchedule($cronSchedule);
-                }
+                $prototype ??= $this->findProto($handler, $method, $context, $graph->getReflection());
 
-                if ($prototype !== null && $returnType !== null) {
-                    $prototype->setReturnType($returnType);
-                }
+                $retry === null or $prototype?->setMethodRetry($retry);
+                $cronSchedule === null or $prototype?->setCronSchedule($cronSchedule);
+                $returnType === null or $prototype?->setReturnType($returnType);
+                $versionBehavior === null or $prototype?->setVersioningBehavior($versionBehavior->value);
             }
 
             $previousRetry = $contextualRetry;

src/Internal/Transport/Router/GetWorkerInfo.php

@@ -44,10 +44,10 @@ public function handle(ServerRequestInterface $request, array $headers, Deferred
     private function workerToArray(WorkerInterface $worker): array
     {
         $workflowMap = static fn(WorkflowPrototype $workflow): array => [
-            'Name'    => $workflow->getID(),
+            'Name' => $workflow->getID(),
             'Queries' => \array_keys($workflow->getQueryHandlers()),
             'Signals' => \array_keys($workflow->getSignalHandlers()),
-            // 'Updates' => $this->keys($workflow->getUpdateHandlers()),
+            'VersioningBehavior' => $workflow->getVersioningBehavior()->value,
         ];
 
         $activityMap = static fn(ActivityPrototype $activity): array => [

src/Workflow/WorkflowVersioningBehavior.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of Temporal package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Temporal\Workflow;
+
+use Doctrine\Common\Annotations\Annotation\Target;
+use Spiral\Attributes\NamedArgumentConstructor;
+use Temporal\Worker\Versioning\VersioningBehavior;
+
+/**
+ * Indicates the versioning behavior of the Workflow.
+ * May only be applied to workflow implementations, not interfaces.
+ *
+ * @Annotation
+ * @NamedArgumentConstructor
+ * @Target({ "METHOD" })
+ *
+ * @see \Temporal\Api\Enums\V1\VersioningBehavior
+ */
+#[\Attribute(\Attribute::TARGET_METHOD), NamedArgumentConstructor]
+final class WorkflowVersioningBehavior
+{
+    public function __construct(
+        /**
+         * The behavior to apply to this workflow.
+         *
+         * See {@link VersioningBehavior} for more information.
+         */
+        public readonly VersioningBehavior $value,
+    ) {}
+}