From f256d5a91823eed9b6ec50cff5547aaaf9c4f6c3 Mon Sep 17 00:00:00 2001
From: Will Sabol <wsabol39@gmail.com>
Date: Tue, 27 Feb 2024 22:00:59 -0600
Subject: [PATCH] append comment to the Response element

---
 src/Twilio/TwiML/TwiML.php                    |  2 ++
 src/Twilio/TwiML/Voice/Comment.php            | 22 +++++++++++++++++++
 src/Twilio/TwiML/VoiceResponse.php            | 12 +++++++++-
 tests/Twilio/Unit/TwiML/Voice/CommentTest.php | 21 ++++++++++++++++++
 4 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 src/Twilio/TwiML/Voice/Comment.php
 create mode 100644 tests/Twilio/Unit/TwiML/Voice/CommentTest.php

diff --git a/src/Twilio/TwiML/TwiML.php b/src/Twilio/TwiML/TwiML.php
index 6e8ceb4a7..de5a21c46 100644
--- a/src/Twilio/TwiML/TwiML.php
+++ b/src/Twilio/TwiML/TwiML.php
@@ -115,6 +115,8 @@ private function buildElement(TwiML $twiml, DOMDocument $document): DOMElement {
         foreach ($twiml->children as $child) {
             if (\is_string($child)) {
                 $element->appendChild($document->createTextNode($child));
+            } elseif (\is_a($child, "Twilio\TwiML\Voice\Comment")) {
+                $element->appendChild($document->createComment($child->children[0]));
             } else {
                 $element->appendChild($this->buildElement($child, $document));
             }
diff --git a/src/Twilio/TwiML/Voice/Comment.php b/src/Twilio/TwiML/Voice/Comment.php
new file mode 100644
index 000000000..615130472
--- /dev/null
+++ b/src/Twilio/TwiML/Voice/Comment.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace Twilio\TwiML\Voice;
+
+use Twilio\TwiML\TwiML;
+
+class Comment extends TwiML {
+    /**
+     * Comment constructor.
+     *
+     * @param string $message Message to comment
+     */
+    public function __construct($message) {
+
+        // "--" is not allowed in xml comments
+        while (strpos($message, "--") !== false) {
+            $message = str_replace("--", "-", $message);
+        }
+
+        parent::__construct('Comment', $message);
+    }
+}
diff --git a/src/Twilio/TwiML/VoiceResponse.php b/src/Twilio/TwiML/VoiceResponse.php
index 6cb9a059f..3c8cf915b 100644
--- a/src/Twilio/TwiML/VoiceResponse.php
+++ b/src/Twilio/TwiML/VoiceResponse.php
@@ -219,4 +219,14 @@ public function stop(): Voice\Stop {
     public function refer($attributes = []): Voice\Refer {
         return $this->nest(new Voice\Refer($attributes));
     }
-}
\ No newline at end of file
+
+    /**
+     * Add Comment child.
+     *
+     * @param string $message The content of the comment
+     * @return Voice\Comment Child element.
+     */
+    public function comment($message): Voice\Comment {
+        return $this->nest(new Voice\Comment($message));
+    }
+}
diff --git a/tests/Twilio/Unit/TwiML/Voice/CommentTest.php b/tests/Twilio/Unit/TwiML/Voice/CommentTest.php
new file mode 100644
index 000000000..0c6a4d02b
--- /dev/null
+++ b/tests/Twilio/Unit/TwiML/Voice/CommentTest.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace TwiML\Voice;
+
+use Twilio\Tests\Unit\TwiML\TwiMLTest;
+use Twilio\TwiML\VoiceResponse;
+
+class CommentTest extends TwiMLTest {
+    public function testCommentToResponse(): void {
+        $response = new VoiceResponse();
+        $response->comment('this is a comment');
+
+        $this->compareXml('<Response><!--this is a comment--></Response>', $response);
+    }
+    public function testSketchyCommentToResponse(): void {
+        $response = new VoiceResponse();
+        $response->comment('this is --- a sketchy ---- comment');
+
+        $this->compareXml('<Response><!--this is - a sketchy - comment--></Response>', $response);
+    }
+}