feat: append comment to the Response element

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));
             }

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);
+    }
+}

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));
     }
-}
+
+    /**
+     * 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));
+    }
+}

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);
+    }
+}