From 435ac1a3b8c4cb072a739dc3d8aa2fbddec750c5 Mon Sep 17 00:00:00 2001
From: Michael Crawford <cerealean@me.com>
Date: Thu, 20 Nov 2014 12:29:15 -0600
Subject: [PATCH] Updated constants based on constant class changes. Also added
 php docblocks to all functions and member variables.

---
 src/Mailgun/Messages/MessageBuilder.php | 168 +++++++++++++++++++++---
 1 file changed, 153 insertions(+), 15 deletions(-)

diff --git a/src/Mailgun/Messages/MessageBuilder.php b/src/Mailgun/Messages/MessageBuilder.php
index 34032bb..dde3aa3 100644
--- a/src/Mailgun/Messages/MessageBuilder.php
+++ b/src/Mailgun/Messages/MessageBuilder.php
@@ -2,9 +2,10 @@
 
 namespace Mailgun\Messages;
 
+use Mailgun\Constants\Api;
+use Mailgun\Constants\ExceptionMessages;
 use Mailgun\Messages\Exceptions\InvalidParameter;
 use Mailgun\Messages\Exceptions\TooManyParameters;
-use Mailgun\Messages\Exceptions\InvalidParameterType;
 
 /*
    This class is used for composing a properly formed
@@ -15,10 +16,24 @@ use Mailgun\Messages\Exceptions\InvalidParameterType;
 
 class MessageBuilder
 {
-
+    /**
+     * @var array
+     */
     protected $message = array();
+
+    /**
+     * @var array
+     */
     protected $variables = array();
+
+    /**
+     * @var array
+     */
     protected $files = array();
+
+    /**
+     * @var array
+     */
     protected $counters = array(
         'recipients' => array(
             'to'  => 0,
@@ -33,6 +48,12 @@ class MessageBuilder
         )
     );
 
+    /**
+     * @param array $params
+     * @param string $key
+     * @param mixed $default
+     * @return mixed
+     */
     protected function safeGet($params, $key, $default)
     {
         if (array_key_exists($key, $params)) {
@@ -42,6 +63,10 @@ class MessageBuilder
         return $default;
     }
 
+    /**
+     * @param array $params
+     * @return mixed|string
+     */
     protected function getFullName($params)
     {
         if (array_key_exists("first", $params)) {
@@ -54,6 +79,11 @@ class MessageBuilder
         return $this->safeGet($params, "full_name", "");
     }
 
+    /**
+     * @param string $address
+     * @param array $variables
+     * @return string
+     */
     protected function parseAddress($address, $variables)
     {
         if (!is_array($variables)) {
@@ -67,6 +97,11 @@ class MessageBuilder
         return $address;
     }
 
+    /**
+     * @param string $headerName
+     * @param string $address
+     * @param array $variables
+     */
     protected function addRecipient($headerName, $address, $variables)
     {
         $compiledAddress = $this->parseAddress($address, $variables);
@@ -83,36 +118,59 @@ class MessageBuilder
         }
     }
 
+    /**
+     * @param string $address
+     * @param array|null $variables
+     * @return mixed
+     * @throws TooManyParameters
+     */
     public function addToRecipient($address, $variables = null)
     {
-        if ($this->counters['recipients']['to'] > RECIPIENT_COUNT_LIMIT) {
-            throw new TooManyParameters(TOO_MANY_PARAMETERS_RECIPIENT);
+        if ($this->counters['recipients']['to'] > Api::RECIPIENT_COUNT_LIMIT) {
+            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_RECIPIENT);
         }
         $this->addRecipient("to", $address, $variables);
 
         return end($this->message['to']);
     }
 
+    /**
+     * @param string $address
+     * @param array|null $variables
+     * @return mixed
+     * @throws TooManyParameters
+     */
     public function addCcRecipient($address, $variables = null)
     {
-        if ($this->counters['recipients']['cc'] > RECIPIENT_COUNT_LIMIT) {
-            throw new TooManyParameters(TOO_MANY_PARAMETERS_RECIPIENT);
+        if ($this->counters['recipients']['cc'] > Api::RECIPIENT_COUNT_LIMIT) {
+            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_RECIPIENT);
         }
         $this->addRecipient("cc", $address, $variables);
 
         return end($this->message['cc']);
     }
 
+    /**
+     * @param string $address
+     * @param array|null $variables
+     * @return mixed
+     * @throws TooManyParameters
+     */
     public function addBccRecipient($address, $variables = null)
     {
-        if ($this->counters['recipients']['bcc'] > RECIPIENT_COUNT_LIMIT) {
-            throw new TooManyParameters(TOO_MANY_PARAMETERS_RECIPIENT);
+        if ($this->counters['recipients']['bcc'] > Api::RECIPIENT_COUNT_LIMIT) {
+            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_RECIPIENT);
         }
         $this->addRecipient("bcc", $address, $variables);
 
         return end($this->message['bcc']);
     }
 
+    /**
+     * @param string $address
+     * @param array|null $variables
+     * @return mixed
+     */
     public function setFromAddress($address, $variables = null)
     {
         $this->addRecipient("from", $address, $variables);
@@ -120,6 +178,11 @@ class MessageBuilder
         return $this->message['from'];
     }
 
+    /**
+     * @param string $address
+     * @param array|null $variables
+     * @return mixed
+     */
     public function setReplyToAddress($address, $variables = null)
     {
         $this->addRecipient("h:reply-to", $address, $variables);
@@ -127,7 +190,11 @@ class MessageBuilder
         return $this->message['h:reply-to'];
     }
 
-    public function setSubject($subject = null)
+    /**
+     * @param string $subject
+     * @return mixed
+     */
+    public function setSubject($subject = "")
     {
         if ($subject == null || $subject == "") {
             $subject = " ";
@@ -137,6 +204,11 @@ class MessageBuilder
         return $this->message['subject'];
     }
 
+    /**
+     * @param string $headerName
+     * @param mixed $headerData
+     * @return mixed
+     */
     public function addCustomHeader($headerName, $headerData)
     {
         if (!preg_match("/^h:/i", $headerName)) {
@@ -147,6 +219,10 @@ class MessageBuilder
         return $this->message[$headerName];
     }
 
+    /**
+     * @param string $textBody
+     * @return string
+     */
     public function setTextBody($textBody)
     {
         if ($textBody == null || $textBody == "") {
@@ -157,6 +233,10 @@ class MessageBuilder
         return $this->message['text'];
     }
 
+    /**
+     * @param string $htmlBody
+     * @return string
+     */
     public function setHtmlBody($htmlBody)
     {
         if ($htmlBody == null || $htmlBody == "") {
@@ -167,6 +247,11 @@ class MessageBuilder
         return $this->message['html'];
     }
 
+    /**
+     * @param string $attachmentPath
+     * @param string|null $attachmentName
+     * @return bool
+     */
     public function addAttachment($attachmentPath, $attachmentName = null)
     {
         if (isset($this->files["attachment"])) {
@@ -187,6 +272,11 @@ class MessageBuilder
         return true;
     }
 
+    /**
+     * @param string $inlineImagePath
+     * @param string|null $inlineImageName
+     * @throws InvalidParameter
+     */
     public function addInlineImage($inlineImagePath, $inlineImageName = null)
     {
         if (preg_match("/^@/", $inlineImagePath)) {
@@ -207,10 +297,14 @@ class MessageBuilder
 
             return true;
         } else {
-            throw new InvalidParameter(INVALID_PARAMETER_INLINE);
+            throw new InvalidParameter(ExceptionMessages::INVALID_PARAMETER_INLINE);
         }
     }
 
+    /**
+     * @param boolean $testMode
+     * @return string
+     */
     public function setTestMode($testMode)
     {
         if (filter_var($testMode, FILTER_VALIDATE_BOOLEAN)) {
@@ -223,9 +317,14 @@ class MessageBuilder
         return $this->message['o:testmode'];
     }
 
+    /**
+     * @param string|int $campaignId
+     * @return string|int
+     * @throws TooManyParameters
+     */
     public function addCampaignId($campaignId)
     {
-        if ($this->counters['attributes']['campaign_id'] < CAMPAIGN_ID_LIMIT) {
+        if ($this->counters['attributes']['campaign_id'] < Api::CAMPAIGN_ID_LIMIT) {
             if (isset($this->message['o:campaign'])) {
                 array_push($this->message['o:campaign'], $campaignId);
             } else {
@@ -235,13 +334,17 @@ class MessageBuilder
 
             return $this->message['o:campaign'];
         } else {
-            throw new TooManyParameters(TOO_MANY_PARAMETERS_CAMPAIGNS);
+            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_CAMPAIGNS);
         }
     }
 
+    /**
+     * @param string $tag
+     * @throws TooManyParameters
+     */
     public function addTag($tag)
     {
-        if ($this->counters['attributes']['tag'] < TAG_LIMIT) {
+        if ($this->counters['attributes']['tag'] < Api::TAG_LIMIT) {
             if (isset($this->message['o:tag'])) {
                 array_push($this->message['o:tag'], $tag);
             } else {
@@ -251,10 +354,14 @@ class MessageBuilder
 
             return $this->message['o:tag'];
         } else {
-            throw new TooManyParameters(TOO_MANY_PARAMETERS_TAGS);
+            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_TAGS);
         }
     }
 
+    /**
+     * @param boolean $enabled
+     * @return mixed
+     */
     public function setDkim($enabled)
     {
         if (filter_var($enabled, FILTER_VALIDATE_BOOLEAN)) {
@@ -267,6 +374,10 @@ class MessageBuilder
         return $this->message["o:dkim"];
     }
 
+    /**
+     * @param boolean $enabled
+     * @return string
+     */
     public function setOpenTracking($enabled)
     {
         if (filter_var($enabled, FILTER_VALIDATE_BOOLEAN)) {
@@ -279,6 +390,10 @@ class MessageBuilder
         return $this->message['o:tracking-opens'];
     }
 
+    /**
+     * @param boolean $enabled
+     * @return string
+     */
     public function setClickTracking($enabled)
     {
         if (filter_var($enabled, FILTER_VALIDATE_BOOLEAN)) {
@@ -293,12 +408,17 @@ class MessageBuilder
         return $this->message['o:tracking-clicks'];
     }
 
+    /**
+     * @param string $timeDate
+     * @param string|null $timeZone
+     * @return string
+     */
     public function setDeliveryTime($timeDate, $timeZone = null)
     {
         if (isset($timeZone)) {
             $timeZoneObj = new \DateTimeZone("$timeZone");
         } else {
-            $timeZoneObj = new \DateTimeZone(\DEFAULT_TIME_ZONE);
+            $timeZoneObj = new \DateTimeZone(Api::DEFAULT_TIME_ZONE);
         }
 
         $dateTimeObj                     = new \DateTime($timeDate, $timeZoneObj);
@@ -308,11 +428,20 @@ class MessageBuilder
         return $this->message['o:deliverytime'];
     }
 
+    /**
+     * @param string $customName
+     * @param mixed $data
+     */
     public function addCustomData($customName, $data)
     {
         $this->message['v:' . $customName] = json_encode($data);
     }
 
+    /**
+     * @param string $parameterName
+     * @param mixed $data
+     * @return mixed
+     */
     public function addCustomParameter($parameterName, $data)
     {
         if (isset($this->message[$parameterName])) {
@@ -326,16 +455,25 @@ class MessageBuilder
         }
     }
 
+    /**
+     * @param array $message
+     */
     public function setMessage($message)
     {
         $this->message = $message;
     }
 
+    /**
+     * @return array
+     */
     public function getMessage()
     {
         return $this->message;
     }
 
+    /**
+     * @return array
+     */
     public function getFiles()
     {
         return $this->files;