Convert envelope trait to abstract class

composer.json

@@ -40,6 +40,7 @@
         "psr/container": "^1.0|^2.0",
         "psr/log": "^2.0|^3.0",
         "symfony/console": "^5.4|^6.0|^7.0",
+        "yiisoft/arrays": "^3.1",
         "yiisoft/definitions": "^3.3.1",
         "yiisoft/factory": "^1.3",
         "yiisoft/friendly-exception": "^1.0",

src/Message/EnvelopeTrait.php → src/Message/Envelope.php

@@ -4,14 +4,11 @@
 
 namespace Yiisoft\Queue\Message;
 
-trait EnvelopeTrait
+abstract class Envelope implements EnvelopeInterface
 {
-    private MessageInterface $message;
-
-    /**
-     * A mirror of {@see MessageInterface::fromData()}
-     */
-    abstract public static function fromMessage(MessageInterface $message): self;
+    public function __construct(protected MessageInterface $message)
+    {
+    }
 
     public static function fromData(string $handlerName, mixed $data, array $metadata = []): MessageInterface
     {
@@ -23,14 +20,6 @@ public function getMessage(): MessageInterface
         return $this->message;
     }
 
-    public function withMessage(MessageInterface $message): self
-    {
-        $instance = clone $this;
-        $instance->message = $message;
-
-        return $instance;
-    }
-
     public function getHandlerName(): string
     {
         return $this->message->getHandlerName();
@@ -48,15 +37,12 @@ public function getMetadata(): array
             [
                 EnvelopeInterface::ENVELOPE_STACK_KEY => array_merge(
                     $this->message->getMetadata()[EnvelopeInterface::ENVELOPE_STACK_KEY] ?? [],
-                    [self::class],
+                    [static::class],
                 ),
             ],
             $this->getEnvelopeMetadata(),
         );
     }
 
-    public function getEnvelopeMetadata(): array
-    {
-        return [];
-    }
+    abstract protected function getEnvelopeMetadata(): array;
 }

src/Message/EnvelopeInterface.php

@@ -15,6 +15,4 @@ interface EnvelopeInterface extends MessageInterface
     public static function fromMessage(MessageInterface $message): self;
 
     public function getMessage(): MessageInterface;
-
-    public function withMessage(MessageInterface $message): self;
 }

src/Message/IdEnvelope.php

@@ -7,34 +7,28 @@
 /**
  * ID envelope allows to identify a message.
  */
-final class IdEnvelope implements EnvelopeInterface
+final class IdEnvelope extends Envelope
 {
-    use EnvelopeTrait;
-
     public const MESSAGE_ID_KEY = 'yii-message-id';
 
     public function __construct(
-        private MessageInterface $message,
-        private string|int|null $id = null,
+        MessageInterface $message,
+        private readonly string|int|null $id,
     ) {
+        parent::__construct($message);
     }
 
     public static function fromMessage(MessageInterface $message): self
     {
         return new self($message, $message->getMetadata()[self::MESSAGE_ID_KEY] ?? null);
     }
 
-    public function setId(string|int|null $id): void
-    {
-        $this->id = $id;
-    }
-
     public function getId(): string|int|null
     {
         return $this->id ?? $this->message->getMetadata()[self::MESSAGE_ID_KEY] ?? null;
     }
 
-    private function getEnvelopeMetadata(): array
+    protected function getEnvelopeMetadata(): array
     {
         return [self::MESSAGE_ID_KEY => $this->getId()];
     }

src/Message/Message.php

@@ -7,9 +7,9 @@
 final class Message implements MessageInterface
 {
     /**
+     * @param string $handlerName A name of a handler which should handle this message.
      * @param mixed $data Message data, encodable by a queue adapter
      * @param array $metadata Message metadata, encodable by a queue adapter
-     * @param string|null $id Message id
      */
     public function __construct(
         private string $handlerName,
@@ -37,12 +37,4 @@ public function getMetadata(): array
     {
         return $this->metadata;
     }
-
-    public function withMetadata(array $metadata): self
-    {
-        $instance = clone $this;
-        $instance->metadata = $metadata;
-
-        return $instance;
-    }
 }

src/Message/MessageInterface.php

@@ -10,22 +10,16 @@ public static function fromData(string $handlerName, mixed $data, array $metadat
 
     /**
      * Returns handler name.
-     *
-     * @return string
      */
     public function getHandlerName(): string;
 
     /**
      * Returns payload data.
-     *
-     * @return mixed
      */
     public function getData(): mixed;
 
     /**
      * Returns message metadata: timings, attempts count, metrics, etc.
-     *
-     * @return array
      */
     public function getMetadata(): array;
 }

src/Middleware/FailureHandling/FailureEnvelope.php

@@ -4,32 +4,28 @@
 
 namespace Yiisoft\Queue\Middleware\FailureHandling;
 
-use Yiisoft\Queue\Message\EnvelopeInterface;
-use Yiisoft\Queue\Message\EnvelopeTrait;
+use Yiisoft\Arrays\ArrayHelper;
+use Yiisoft\Queue\Message\Envelope;
 use Yiisoft\Queue\Message\MessageInterface;
 
-final class FailureEnvelope implements EnvelopeInterface
+final class FailureEnvelope extends Envelope
 {
-    use EnvelopeTrait;
-
     public const FAILURE_META_KEY = 'failure-meta';
 
     public function __construct(
-        private MessageInterface $message,
-        private array $meta = [],
+        MessageInterface $message,
+        private readonly array $failureMeta = [],
     ) {
+        parent::__construct($message);
     }
 
     public static function fromMessage(MessageInterface $message): self
     {
         return new self($message, $message->getMetadata()[self::FAILURE_META_KEY] ?? []);
     }
 
-    public function getMetadata(): array
+    protected function getEnvelopeMetadata(): array
     {
-        $meta = $this->message->getMetadata();
-        $meta[self::FAILURE_META_KEY] = array_merge($meta[self::FAILURE_META_KEY] ?? [], $this->meta);
-
-        return $meta;
+        return [self::FAILURE_META_KEY => ArrayHelper::merge($this->message->getMetadata()[self::FAILURE_META_KEY] ?? [], $this->failureMeta)];
     }
 }

tests/Unit/Message/JsonMessageSerializerTest.php

@@ -219,7 +219,7 @@ public function testRestoreOriginalMessageClass(): void
 
     public function testRestoreOriginalMessageClassWithEnvelope(): void
     {
-        $message = new IdEnvelope(new TestMessage());
+        $message = new IdEnvelope(new TestMessage(), 1);
         $serializer = $this->createSerializer();
         $serializer->unserialize($serializer->serialize($message));
 

tests/Unit/Middleware/FailureHandling/Implementation/SendAgainMiddlewareTest.php

@@ -151,9 +151,6 @@ public function testQueueSendingStrategies(
             $this->expectExceptionMessage('testException');
         }
 
-        $metaInitial = [FailureEnvelope::FAILURE_META_KEY => $metaInitial];
-        $metaResult = [FailureEnvelope::FAILURE_META_KEY => $metaResult];
-
         $handler = $this->getHandler($metaResult, $suites);
         $queue = $this->getPreparedQueue($metaResult, $suites);
 
@@ -162,7 +159,7 @@ public function testQueueSendingStrategies(
             new Message(
                 'test',
                 null,
-                $metaInitial
+                [FailureEnvelope::FAILURE_META_KEY => $metaInitial]
             ),
             new Exception('testException'),
             $queue
@@ -194,7 +191,7 @@ private function getHandler(array $metaResult, bool $suites): MessageFailureHand
         $pipelineAssertion = static function (FailureHandlingRequest $request) use (
             $metaResult
         ): FailureHandlingRequest {
-            Assert::assertEquals($metaResult, $request->getMessage()->getMetadata());
+            Assert::assertEquals($metaResult, $request->getMessage()->getMetadata()[FailureEnvelope::FAILURE_META_KEY] ?? []);
 
             throw $request->getException();
         };
@@ -209,7 +206,7 @@ private function getHandler(array $metaResult, bool $suites): MessageFailureHand
     private function getPreparedQueue(array $metaResult, bool $suites): QueueInterface
     {
         $queueAssertion = static function (MessageInterface $message) use ($metaResult): MessageInterface {
-            Assert::assertEquals($metaResult, $message->getMetadata());
+            Assert::assertEquals($metaResult, $message->getMetadata()[FailureEnvelope::FAILURE_META_KEY] ?? []);
 
             return $message;
         };