Introduce abstract Message class

Author: vjik

docs/guide/en/configuration-manual.md

@@ -79,7 +79,7 @@ $queue = new Queue(
 );
 
 // Now you can push messages
-$message = new \Yiisoft\Queue\Message\Message('file-download', ['url' => 'https://example.com/file.pdf']);
+$message = new \Yiisoft\Queue\Message\SimpleMessage('file-download', ['url' => 'https://example.com/file.pdf']);
 $queue->push($message);
 ```
 

docs/guide/en/message-handler-advanced.md

@@ -17,9 +17,9 @@ Handler definitions are configured in:
 Use a short stable message type when pushing a `Message` instead of a PHP class name:
 
 ```php
-use Yiisoft\Queue\Message\Message;
+use Yiisoft\Queue\Message\SimpleMessage;
 
-new Message('send-email', ['data' => '...']); // "send-email" is the message type here
+new SimpleMessage('send-email', ['data' => '...']); // "send-email" is the message type here
 ```
 
 **Config**:

docs/guide/en/message-handler.md

@@ -13,7 +13,7 @@ If your handler implements `Yiisoft\Queue\Message\MessageHandlerInterface`, you
 **Message**:
 
 ```php
-new \Yiisoft\Queue\Message\Message(\App\Queue\RemoteFileHandler::class, ['url' => '...']);
+new \Yiisoft\Queue\Message\SimpleMessage(\App\Queue\RemoteFileHandler::class, ['url' => '...']);
 ```
 
 **Handler**:

docs/guide/en/messages-and-handlers.md

@@ -33,7 +33,7 @@ This means the producer and consumer can be:
 A message carries just enough data to perform the work:
 
 ```php
-new \Yiisoft\Queue\Message\Message('send-email', [
+new \Yiisoft\Queue\Message\SimpleMessage('send-email', [
     'to'      => 'user@example.com',
     'subject' => 'Welcome',
 ]);

docs/guide/en/queue-names.md

@@ -68,7 +68,7 @@ Pushing a message via DI:
 
 ```php
 use Yiisoft\Queue\QueueInterface;
-use Yiisoft\Queue\Message\Message;
+use Yiisoft\Queue\Message\SimpleMessage;
 
 final readonly class SendWelcomeEmail
 {
@@ -78,7 +78,7 @@ final readonly class SendWelcomeEmail
 
     public function run(string $email): void
     {
-        $this->queue->push(new Message('send-email', ['to' => $email]));
+        $this->queue->push(new SimpleMessage('send-email', ['to' => $email]));
     }
 }
 ```
@@ -105,7 +105,7 @@ If you have multiple queue names, inject `QueueProviderInterface` and call `get(
 
 ```php
 use Yiisoft\Queue\Provider\QueueProviderInterface;
-use Yiisoft\Queue\Message\Message;
+use Yiisoft\Queue\Message\SimpleMessage;
 
 final readonly class SendTransactionalEmail
 {
@@ -117,7 +117,7 @@ final readonly class SendTransactionalEmail
     {
         $this->queueProvider
             ->get('emails')
-            ->push(new Message('send-email', ['to' => $email]));
+            ->push(new SimpleMessage('send-email', ['to' => $email]));
     }
 }
 ```

docs/guide/en/usage.md

@@ -5,7 +5,7 @@
 For example, if you need to download and save a file, you can create a message like this:
 
 ```php
-$message = new \Yiisoft\Queue\Message\Message(
+$message = new \Yiisoft\Queue\Message\SimpleMessage(
     RemoteFileHandler::class,
     ['url' => $url, 'destinationFile' => $filename]
 );

src/Message/Envelope.php

@@ -4,6 +4,8 @@
 
 namespace Yiisoft\Queue\Message;
 
+use LogicException;
+
 abstract class Envelope implements MessageInterface
 {
     /**
@@ -23,9 +25,11 @@ public function __construct(MessageInterface $message, array $metadata)
         $this->message = $message;
     }
 
-    final public static function fromData(string $type, mixed $data, array $metadata = []): static
+    final public static function fromData(string $type, mixed $data): static
     {
-        return static::fromMessage(Message::fromData($type, $data, $metadata));
+        throw new LogicException(
+            'Envelopes cannot be created via "fromData()". Wrap an existing "MessageInterface" instance instead.',
+        );
     }
 
     abstract public static function fromMessage(MessageInterface $message): static;
@@ -49,4 +53,9 @@ final public function getMetadata(): array
     {
         return $this->metadata;
     }
+
+    final public function withMetadata(array $metadata): static
+    {
+        return static::fromMessage($this->message->withMetadata($metadata));
+    }
 }

src/Message/JsonMessageSerializer.php

@@ -54,15 +54,15 @@ public function unserialize(string $value): MessageInterface
             throw new InvalidArgumentException('Metadata must be an array. Got ' . get_debug_type($meta) . '.');
         }
 
-        $class = $meta['message-class'] ?? Message::class;
+        $class = $meta['message-class'] ?? SimpleMessage::class;
         // Don't check subclasses when it's a default class: that's faster
-        if ($class !== Message::class && !is_subclass_of($class, MessageInterface::class)) {
-            $class = Message::class;
+        if ($class !== SimpleMessage::class && !is_subclass_of($class, MessageInterface::class)) {
+            $class = SimpleMessage::class;
         }
 
         /**
          * @var class-string<MessageInterface> $class
          */
-        return $class::fromData($type, $payload['data'] ?? null, $meta);
+        return $class::fromData($type, $payload['data'] ?? null)->withMetadata($meta);
     }
 }

src/Message/Message.php

@@ -4,38 +4,22 @@
 
 namespace Yiisoft\Queue\Message;
 
-final class Message implements MessageInterface
+abstract class Message implements MessageInterface
 {
     /**
-     * @param string $type A message type used to resolve the handler.
-     * @param mixed $data Message data, encodable by a queue adapter
-     * @param array $metadata Message metadata, encodable by a queue adapter
-     *
-     * @psalm-param array<string, mixed> $metadata
+     * @psalm-var array<string, mixed>
      */
-    public function __construct(
-        private readonly string $type,
-        private readonly mixed $data,
-        private array $metadata = [],
-    ) {}
+    private array $metadata = [];
 
-    public static function fromData(string $type, mixed $data, array $metadata = []): MessageInterface
+    final public function getMetadata(): array
     {
-        return new self($type, $data, $metadata);
-    }
-
-    public function getType(): string
-    {
-        return $this->type;
-    }
-
-    public function getData(): mixed
-    {
-        return $this->data;
+        return $this->metadata;
     }
 
-    public function getMetadata(): array
+    final public function withMetadata(array $metadata): static
     {
-        return $this->metadata;
+        $new = clone $this;
+        $new->metadata = $metadata;
+        return $new;
     }
 }

src/Message/MessageInterface.php

@@ -6,7 +6,7 @@
 
 interface MessageInterface
 {
-    public static function fromData(string $type, mixed $data, array $metadata = []): self;
+    public static function fromData(string $type, mixed $data): self;
 
     /**
      * Returns message type.
@@ -24,4 +24,11 @@ public function getData(): mixed;
      * @return array<string, mixed>
      */
     public function getMetadata(): array;
+
+    /**
+     * Returns a new instance with the given message metadata.
+     *
+     * @param array<string, mixed> $metadata
+     */
+    public function withMetadata(array $metadata): static;
 }