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/Envelope.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Queue\Message;
+
+abstract class Envelope implements EnvelopeInterface
+{
+    private ?array $metadata = null;
+
+    public function __construct(protected MessageInterface $message)
+    {
+    }
+
+    /** @psalm-suppress MoreSpecificReturnType */
+    public static function fromData(string $handlerName, mixed $data, array $metadata = []): static
+    {
+        /** @psalm-suppress LessSpecificReturnStatement */
+        return static::fromMessage(Message::fromData($handlerName, $data, $metadata));
+    }
+
+    public function getMessage(): MessageInterface
+    {
+        return $this->message;
+    }
+
+    public function getHandlerName(): string
+    {
+        return $this->message->getHandlerName();
+    }
+
+    public function getData(): mixed
+    {
+        return $this->message->getData();
+    }
+
+    public function getMetadata(): array
+    {
+        if ($this->metadata === null) {
+            $this->metadata = array_merge(
+                $this->message->getMetadata(),
+                [
+                    EnvelopeInterface::ENVELOPE_STACK_KEY => array_merge(
+                        $this->message->getMetadata()[EnvelopeInterface::ENVELOPE_STACK_KEY] ?? [],
+                        [static::class],
+                    ),
+                ],
+                $this->getEnvelopeMetadata(),
+            );
+        }
+
+        return $this->metadata;
+    }
+
+    abstract protected function getEnvelopeMetadata(): array;
+}

src/Message/EnvelopeInterface.php

@@ -12,9 +12,7 @@ interface EnvelopeInterface extends MessageInterface
     /** @psalm-suppress MissingClassConstType */
     public const ENVELOPE_STACK_KEY = 'envelopes';
 
-    public static function fromMessage(MessageInterface $message): self;
+    public static function fromMessage(MessageInterface $message): static;
 
     public function getMessage(): MessageInterface;
-
-    public function withMessage(MessageInterface $message): self;
 }

src/Message/IdEnvelope.php

@@ -7,34 +7,40 @@
 /**
  * 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
+    public static function fromMessage(MessageInterface $message): static
     {
-        $this->id = $id;
+        /** @var mixed $rawId */
+        $rawId = $message->getMetadata()[self::MESSAGE_ID_KEY] ?? null;
+
+        /** @var int|string|null $id */
+        $id = match (true) {
+            $rawId === null => null,
+            is_string($rawId) => $rawId,
+            is_int($rawId) => $rawId,
+            is_object($rawId) && method_exists($rawId, '__toString') => (string)$rawId,
+            default => throw new \InvalidArgumentException(sprintf('Message ID must be string|int|null, %s given.', get_debug_type($rawId))),
+        };
+
+        return new self($message, $id);
     }
 
     public function getId(): string|int|null
     {
-        return $this->id ?? $this->message->getMetadata()[self::MESSAGE_ID_KEY] ?? null;
+        return $this->id;
     }
 
-    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,34 @@
 
 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 $metadata = [],
     ) {
+        parent::__construct($message);
     }
 
-    public static function fromMessage(MessageInterface $message): self
+    public static function fromMessage(MessageInterface $message): static
     {
-        return new self($message, $message->getMetadata()[self::FAILURE_META_KEY] ?? []);
+        /** @var array $metadata */
+        $metadata = $message->getMetadata()[self::FAILURE_META_KEY] ?? [];
+
+        return new self($message, $metadata);
     }
 
-    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);
+        /** @var array $metadata */
+        $metadata = $this->message->getMetadata()[self::FAILURE_META_KEY] ?? [];
 
-        return $meta;
+        return [self::FAILURE_META_KEY => ArrayHelper::merge($metadata, $this->metadata)];
     }
 }

tests/App/DummyEnvelope.php

@@ -4,19 +4,18 @@
 
 namespace Yiisoft\Queue\Tests\App;
 
-use Yiisoft\Queue\Message\EnvelopeInterface;
-use Yiisoft\Queue\Message\EnvelopeTrait;
+use Yiisoft\Queue\Message\Envelope;
 use Yiisoft\Queue\Message\MessageInterface;
 
-final class DummyEnvelope implements EnvelopeInterface
+final class DummyEnvelope extends Envelope
 {
-    use EnvelopeTrait;
-
-    public static function fromMessage(MessageInterface $message): self
+    public static function fromMessage(MessageInterface $message): static
     {
-        $instance = new self();
-        $instance->message = $message;
+        return new self($message);
+    }
 
-        return $instance;
+    protected function getEnvelopeMetadata(): array
+    {
+        return [];
     }
 }

tests/Unit/Message/EnvelopeTraitTest.php

@@ -5,16 +5,10 @@
 namespace Yiisoft\Queue\Tests\Unit\Message;
 
 use PHPUnit\Framework\TestCase;
-use Yiisoft\Queue\Message\Message;
 use Yiisoft\Queue\Tests\App\DummyEnvelope;
 
 final class EnvelopeTraitTest extends TestCase
 {
-    private function createTestEnvelope(): DummyEnvelope
-    {
-        return new DummyEnvelope();
-    }
-
     public function testFromData(): void
     {
         $handlerName = 'test-handler';
@@ -29,21 +23,4 @@ public function testFromData(): void
         $this->assertArrayHasKey('meta', $envelope->getMetadata());
         $this->assertSame('data', $envelope->getMetadata()['meta']);
     }
-
-    public function testWithMessage(): void
-    {
-        $originalMessage = new Message('original-handler', 'original-data');
-        $newMessage = new Message('new-handler', 'new-data');
-
-        $envelope = $this->createTestEnvelope();
-        $envelope = $envelope->withMessage($originalMessage);
-
-        $this->assertSame($originalMessage, $envelope->getMessage());
-
-        $newEnvelope = $envelope->withMessage($newMessage);
-
-        $this->assertNotSame($envelope, $newEnvelope);
-        $this->assertSame($newMessage, $newEnvelope->getMessage());
-        $this->assertSame($originalMessage, $envelope->getMessage());
-    }
 }