Add support for encoding

Author: nickdnk

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 4.1.0 - 2025-03-19
+* Add support for `encoding` via `SMSMessage::ENCODING_UTF8` and `SMSMessage::Encoding_UCS2`. Default is `null`, which
+uses `UTF8`. Note that `UTF8` means that the GSM-7 character set is used. `UCS2` adds the ability to use emojis, but
+increases the length (and hence cost) of your messages. See https://gatewayapi.com/docs/apis/rest/#basic-use.
+
 ## 4.0.0 - 2025-02-05
 * Require at least PHP 7.3.
 * Test against PHP 8.4.

src/Entities/Request/SMSMessage.php

@@ -18,6 +18,7 @@
  * @property int|null    $sendtime
  * @property string|null $userref
  * @property string|null $callback_url
+ * @property string|null $encoding
  * @package nickdnk\GatewayAPI
  */
 class SMSMessage implements JsonSerializable
@@ -29,7 +30,20 @@ class SMSMessage implements JsonSerializable
     const CLASS_PREMIUM  = 'premium';
     const CLASS_SECRET   = 'secret';
 
-    private $message, $sender, $recipients, $tags, $sendtime, $class, $userref, $callbackUrl;
+    /**
+     * Passing `UTF8` as encoding means the message will use the GSM-7 character set. To use emojis etc., use
+     * `SMSMessage::ENCODING_UCS2`.
+     * @link https://gatewayapi.com/docs/glossary/#gsm-7
+     */
+    const ENCODING_UTF8 = 'UTF8';
+    /**
+     * Passing `UCS2` as encoding means the message will use the UCS2 character set, which allows for emojis but
+     * increases message length.
+     * @link https://gatewayapi.com/docs/glossary/#ucs-2
+     */
+    const ENCODING_UCS2 = 'UCS2';
+
+    private $message, $sender, $recipients, $tags, $sendtime, $class, $userref, $callbackUrl, $encoding;
 
     public static function constructFromArray(array $array): SMSMessage
     {
@@ -61,7 +75,8 @@ public static function constructFromArray(array $array): SMSMessage
                 $array['tags'],
                 array_key_exists('sendtime', $array) ? $array['sendtime'] : null,
                 $array['class'],
-                array_key_exists('callback_url', $array) ? $array['callback_url'] : null
+                array_key_exists('callback_url', $array) ? $array['callback_url'] : null,
+                array_key_exists('encoding', $array) ? $array['encoding'] : null
             );
 
         }
@@ -81,10 +96,11 @@ public static function constructFromArray(array $array): SMSMessage
      * @param int|null    $sendTime
      * @param string      $class
      * @param string|null $callbackUrl
+     * @param string|null $encoding
      */
     public function __construct(string $message, string $senderName, array $recipients = [],
         ?string $userReference = null, array $tags = [], ?int $sendTime = null, string $class = self::CLASS_STANDARD,
-        ?string $callbackUrl = null
+        ?string $callbackUrl = null, ?string $encoding = null
     )
     {
 
@@ -95,6 +111,7 @@ public function __construct(string $message, string $senderName, array $recipien
         $this->tags = $tags;
         $this->sendtime = $sendTime;
         $this->callbackUrl = $callbackUrl;
+        $this->setEncoding($encoding);
         $this->setClass($class);
 
     }
@@ -130,6 +147,21 @@ public function setClass(string $class): void
 
     }
 
+    public function setEncoding(?string $encoding): void
+    {
+
+        if ($encoding !== self::ENCODING_UTF8
+            && $encoding !== self::ENCODING_UCS2
+            && $encoding !== null) {
+            throw new InvalidArgumentException(
+                'SMS encoding must be one of the provided constants or null. Received value: ' . $encoding
+            );
+        }
+
+        $this->encoding = $encoding;
+
+    }
+
     public function getClass(): string
     {
 
@@ -174,6 +206,11 @@ public function getCallbackUrl(): ?string
         return $this->callbackUrl;
     }
 
+    public function getEncoding(): ?string
+    {
+        return $this->encoding;
+    }
+
     public function setSendTime(int $sendTime): void
     {
 
@@ -257,6 +294,10 @@ public function jsonSerialize(): array
             $json['callback_url'] = $this->callbackUrl;
         }
 
+        if ($this->encoding !== null) {
+            $json['encoding'] = $this->encoding;
+        }
+
         return $json;
     }
 

tests/SMSMessageTest.php

@@ -21,7 +21,7 @@ public function testConstructFromJSON()
                     new Recipient(4561232323, ['Joe', '22']),
                     new Recipient(4577364722, ['Mark', '23'])
                 ], 'reference text', ['%NAME%', '%AGE%'], 1585835858, SMSMessage::CLASS_SECRET,
-                    'https://example.com/callback'
+                    'https://example.com/callback', SMSMessage::ENCODING_UCS2
                 )
             )
         );
@@ -39,6 +39,7 @@ public function testConstructFromJSON()
         $this->assertEquals(1585835858, $self->getSendtime());
 
         $this->assertEquals('https://example.com/callback', $self->getCallbackUrl());
+        $this->assertEquals('UCS2', $self->getEncoding());
 
     }
 
@@ -168,4 +169,32 @@ public function testCallbackUrl()
 
         $this->assertEquals('https://example.com/callback', $message->getCallbackUrl());
     }
+
+    public function testEncodingUCS2()
+    {
+
+        $message = new SMSMessage('test', 'sender');
+        $message->setEncoding(SMSMessage::ENCODING_UCS2);
+
+        $this->assertEquals('UCS2', $message->getEncoding());
+    }
+
+    public function testEncodingUTF8()
+    {
+
+        $message = new SMSMessage('test', 'sender');
+        $message->setEncoding(SMSMessage::ENCODING_UTF8);
+
+        $this->assertEquals('UTF8', $message->getEncoding());
+    }
+
+    public function testEncodingNull()
+    {
+
+        $message = new SMSMessage('test', 'sender');
+        $message->setEncoding(SMSMessage::ENCODING_UTF8);
+        $message->setEncoding(null);
+
+        $this->assertNull($message->getEncoding());
+    }
 }