[domain] outgoing MMS support

Author: capcom6

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### New Features
+
+#### MMS
+
+- **Outgoing MMS support** — send MMS messages with an optional subject, text body, and base64-encoded attachments. Pass an `MmsMessage` instead of text to `Message` or `MessageBuilder`; subject, text, and attachment content are encrypted when using `Encryptor`.
+  ```php
+  $mms = new MmsMessage('Subject', 'Text', [
+      new MmsAttachment('image/png', base64_encode($data), 'picture.png'),
+  ]);
+
+  $state = $client->SendMessage(new Message($mms, ['+15550100']));
+  ```

README.md

@@ -11,7 +11,7 @@ A modern PHP client for the [SMSGate](https://sms-gate.app) API: send SMS messag
 
 ## 📖 About
 
-`capcom6/android-sms-gateway` is a type-safe PHP library for the SMSGate 3rd-party API. It covers messages (send, state, listing, cancellation), inbox refresh with attachment download, devices, webhooks, settings, logs, health checks, and the JWT token lifecycle, with a fluent `MessageBuilder` for message construction and an optional `Encryptor` for end-to-end encryption. Works with any PSR-18 HTTP client (Guzzle, curl, or others) and PHP 7.4+.
+`capcom6/android-sms-gateway` is a type-safe PHP library for the SMSGate 3rd-party API. It covers SMS and MMS messages (send, state, listing, cancellation), inbox refresh with attachment download, devices, webhooks, settings, logs, health checks, and the JWT token lifecycle, with a fluent `MessageBuilder` for message construction and an optional `Encryptor` for end-to-end encryption. Works with any PSR-18 HTTP client (Guzzle, curl, or others) and PHP 7.4+.
 
 ## 📚 Table of Contents
 
@@ -32,6 +32,8 @@ A modern PHP client for the [SMSGate](https://sms-gate.app) API: send SMS messag
 ## ⭐ Features
 
 - Fluent `MessageBuilder` for messages and `SettingsBuilder` for settings
+- SMS messages with delivery reports, priority, TTL, and message cancellation
+- Outgoing MMS messages with subject, text, and attachments
 - PSR-18 HTTP client and PSR-17 factories, auto-discovered
 - Basic and JWT authentication with token generation and revocation
 - Webhooks, devices, settings, logs, and health checks

src/Domain/Message.php

@@ -13,11 +13,18 @@ class Message implements SerializableInterface {
      * Message ID, will be generated automatically if not set
      */
     private ?string $id;
+
     /**
      * Message text
      * Long message will be divided into parts
      */
     private string $message;
+    /**
+     * MMS message content (mutually exclusive with text/data messages)
+     * @var MmsMessage|null
+     */
+    private ?MmsMessage $mmsMessage;
+
     /**
      * Time to live in seconds
      * If message is not received by device in this time, it will be failed
@@ -50,10 +57,11 @@ class Message implements SerializableInterface {
     private ?string $validUntil;
 
     /**
+     * @param string|MmsMessage $message
      * @param array<string> $phoneNumbers
      */
     public function __construct(
-        string $message,
+        $message,
         array $phoneNumbers,
         ?string $id = null,
         ?int $ttl = null,
@@ -67,14 +75,30 @@ public function __construct(
         }
 
         $this->id = $id;
-        $this->message = $message;
         $this->ttl = $ttl;
         $this->simNumber = $simNumber;
         $this->withDeliveryReport = $withDeliveryReport;
         $this->phoneNumbers = $phoneNumbers;
         $this->isEncrypted = false;
         $this->priority = $priority;
         $this->validUntil = $validUntil;
+
+        if ($message instanceof MmsMessage) {
+            $this->mmsMessage = $message;
+            $this->message = '';
+        } else {
+            $this->message = $message;
+            $this->mmsMessage = null;
+        }
+    }
+
+
+    /**
+     * Get MMS message content (null if not set)
+     * @return MmsMessage|null
+     */
+    public function MmsMessage(): ?MmsMessage {
+        return $this->mmsMessage;
     }
 
     public function Encrypt(Encryptor $encryptor): self {
@@ -88,19 +112,46 @@ public function Encrypt(Encryptor $encryptor): self {
             fn(string $phoneNumber) => $encryptor->Encrypt($phoneNumber),
             $this->phoneNumbers
         );
+
+        if ($this->mmsMessage !== null) {
+            $this->mmsMessage = new MmsMessage(
+                $this->mmsMessage->Subject() !== null
+                ? $encryptor->Encrypt($this->mmsMessage->Subject())
+                : null,
+                $this->mmsMessage->Text() !== null
+                ? $encryptor->Encrypt($this->mmsMessage->Text())
+                : null,
+                array_map(
+                    fn(MmsAttachment $attachment) => new MmsAttachment(
+                        $attachment->ContentType(),
+                        $encryptor->Encrypt($attachment->Data()),
+                        $attachment->Name() !== null
+                        ? $encryptor->Encrypt($attachment->Name())
+                        : null
+                    ),
+                    $this->mmsMessage->Attachments()
+                )
+            );
+        }
+
         return $this;
     }
 
     public function ToObject(): object {
         $obj = (object) [
             'id' => $this->id,
-            'message' => $this->message,
             'simNumber' => $this->simNumber,
             'withDeliveryReport' => $this->withDeliveryReport,
             'isEncrypted' => $this->isEncrypted,
             'phoneNumbers' => $this->phoneNumbers,
         ];
 
+        if ($this->mmsMessage !== null) {
+            $obj->mmsMessage = $this->mmsMessage->ToObject();
+        } else {
+            $obj->message = $this->message;
+        }
+
         if ($this->priority !== null) {
             $obj->priority = $this->priority;
         }

src/Domain/MessageBuilder.php

@@ -14,9 +14,9 @@ class MessageBuilder {
     private ?string $id = null;
 
     /**
-     * @var string
+     * @var string|MmsMessage
      */
-    private string $message;
+    private $message;
 
     /**
      * @var int|null
@@ -50,10 +50,10 @@ class MessageBuilder {
     private ?string $validUntil = null;
 
     /**
-     * @param string $message
+     * @param string|MmsMessage $message
      * @param array<string> $phoneNumbers
      */
-    public function __construct(string $message, array $phoneNumbers) {
+    public function __construct($message, array $phoneNumbers) {
         $this->message = $message;
         $this->phoneNumbers = $phoneNumbers;
     }
@@ -72,10 +72,10 @@ public function setId(?string $id): self {
     /**
      * Set message text
      *
-     * @param string $message
+     * @param string|MmsMessage $message
      * @return $this
      */
-    public function setMessage(string $message): self {
+    public function setMessage($message): self {
         $this->message = $message;
         return $this;
     }

src/Domain/MmsAttachment.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace AndroidSmsGateway\Domain;
+
+/**
+ * A single attachment of an MMS message.
+ */
+final class MmsAttachment {
+    /**
+     * MIME type of the attachment (e.g. image/png)
+     * @var string
+     */
+    private string $contentType;
+
+    /**
+     * Base64-encoded attachment content
+     * @var string
+     */
+    private string $data;
+
+    /**
+     * Optional file name of the attachment
+     * @var string|null
+     */
+    private ?string $name;
+
+    /**
+     * @param string $contentType MIME type of the attachment (e.g. image/png)
+     * @param string $data Base64-encoded attachment content
+     * @param string|null $name Optional file name of the attachment
+     */
+    public function __construct(string $contentType, string $data, ?string $name = null) {
+        $this->contentType = $contentType;
+        $this->data = $data;
+        $this->name = $name;
+    }
+
+    public function ContentType(): string {
+        return $this->contentType;
+    }
+
+    public function Data(): string {
+        return $this->data;
+    }
+
+    public function Name(): ?string {
+        return $this->name;
+    }
+
+    public function ToObject(): \stdClass {
+        $obj = (object) [
+            'contentType' => $this->contentType,
+            'name' => $this->name,
+            'data' => $this->data,
+        ];
+
+        if ($this->name === null) {
+            unset($obj->name);
+        }
+
+        return $obj;
+    }
+}

src/Domain/MmsMessage.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace AndroidSmsGateway\Domain;
+
+/**
+ * An MMS message with optional subject, text and attachments.
+ */
+final class MmsMessage {
+    /**
+     * Optional subject of the MMS
+     * @var string|null
+     */
+    private ?string $subject;
+
+    /**
+     * Optional text body of the MMS
+     * @var string|null
+     */
+    private ?string $text;
+
+    /**
+     * List of attachments. Omitted entirely from the wire when empty.
+     * @var array<MmsAttachment>
+     */
+    private array $attachments;
+
+    /**
+     * @param string|null $subject Optional subject of the MMS
+     * @param string|null $text Optional text body of the MMS
+     * @param array<MmsAttachment> $attachments List of attachments
+     */
+    public function __construct(?string $subject = null, ?string $text = null, array $attachments = []) {
+        $this->subject = $subject;
+        $this->text = $text;
+        $this->attachments = $attachments;
+    }
+
+    public function Subject(): ?string {
+        return $this->subject;
+    }
+
+    public function Text(): ?string {
+        return $this->text;
+    }
+
+    /**
+     * @return array<MmsAttachment>
+     */
+    public function Attachments(): array {
+        return $this->attachments;
+    }
+
+    public function ToObject(): \stdClass {
+        $obj = (object) [
+            'subject' => $this->subject,
+            'text' => $this->text,
+            'attachments' => array_map(
+                static fn(MmsAttachment $attachment) => $attachment->ToObject(),
+                $this->attachments
+            ),
+        ];
+
+        if ($this->subject === null) {
+            unset($obj->subject);
+        }
+
+        if ($this->text === null) {
+            unset($obj->text);
+        }
+
+        if (count($this->attachments) === 0) {
+            unset($obj->attachments);
+        }
+
+        return $obj;
+    }
+}

tests/ClientTest.php

@@ -113,7 +113,7 @@ public function testServer(): void {
         );
         $client = new Client($login, $password, Client::DEFAULT_URL, $curlClient);
 
-        $message = new Message(date('Y-m-d H:i:s'), [$phoneNumber]);
+        $message = new Message('Test message from `client-php`' . PHP_EOL . date('Y-m-d H:i:s'), [$phoneNumber]);
 
         $messageState = $client->SendMessage($message);
         $this->assertInstanceOf(MessageState::class, $messageState);