Added support for Notifications in Shipping API by email

src/Ups/Entity/EmailMessage.php

@@ -0,0 +1,222 @@
+<?php
+namespace Ups\Entity;
+
+use DOMDocument;
+use DOMElement;
+use Ups\NodeInterface;
+
+class EmailMessage implements NodeInterface
+{
+
+    /**
+     * @var array
+     */
+    private $emailAddresses = array();
+
+    /**
+     * @var string
+     */
+    private $undeliverableEmailAddress;
+
+    /**
+     * @var string
+     */
+    private $fromEmailAddress;
+
+    /**
+     * @var string
+     */
+    private $fromName;
+
+    /**
+     * @var string
+     */
+    private $memo;
+
+    /**
+     * @var string
+     */
+    private $subject;
+
+    /**
+     * @var string
+     */
+    private $subjectCode;
+
+    /**
+     * Subject codes
+     */
+    const SUBJECT_CODE_SHIPMENT_REFERENCE_NR1 = '01';
+    const SUBJECT_CODE_SHIPMENT_REFERENCE_NR2 = '02';
+    const SUBJECT_CODE_SHIPMENT_PACKAGE_NR1 = '03';
+    const SUBJECT_CODE_SHIPMENT_PACKAGE_NR2 = '04';
+    const SUBJECT_CODE_SUBJECT_TEXT = '08'; // Return only
+
+    /**
+     * @param null|DOMDocument $document
+     * @return DOMElement
+     */
+    public function toNode(DOMDocument $document = null)
+    {
+        if (null === $document) {
+            $document = new DOMDocument();
+        }
+
+        $node = $document->createElement('EMailMessage');
+
+        foreach($this->getEmailAddresses() as $email) {
+            $node->appendChild($document->createElement('EMailAddress', $email));
+        }
+
+        if($this->getUndeliverableEmailAddress() !== null) {
+            $node->appendChild($document->createElement('UndeliverableEMailAddress', $this->getUndeliverableEmailAddress()));
+        }
+
+        if($this->getFromEmailAddress() !== null) {
+            $node->appendChild($document->createElement('FromEMailAddress', $this->getFromEmailAddress()));
+        }
+
+        if($this->getFromName() !== null) {
+            $node->appendChild($document->createElement('FromName', $this->getFromName()));
+        }
+
+        if($this->getMemo() !== null) {
+            $node->appendChild($document->createElement('Memo', $this->getMemo()));
+        }
+
+        if($this->getSubject() !== null) {
+            $node->appendChild($document->createElement('Subject', $this->getSubject()));
+        }
+
+        if($this->getSubjectCode() !== null) {
+            $node->appendChild($document->createElement('SubjectCode', $this->getSubjectCode()));
+        }
+
+        return $node;
+    }
+
+    /**
+     * @return array
+     */
+    public function getEmailAddresses()
+    {
+        return $this->emailAddresses;
+    }
+
+    /**
+     * @param array $emailAddress
+     */
+    public function setEmailAddresses(array $emailAddresses)
+    {
+        if(count($emailAddresses) > 5) {
+            throw new \Exception('Maximum of 5 emailaddresses allowed');
+        }
+
+        $this->emailAddresses = $emailAddresses;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getUndeliverableEmailAddress()
+    {
+        return $this->undeliverableEmailAddress;
+    }
+
+    /**
+     * @param mixed $undeliverableEmailAddress
+     */
+    public function setUndeliverableEmailAddress($undeliverableEmailAddress)
+    {
+        $this->undeliverableEmailAddress = $undeliverableEmailAddress;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getFromEmailAddress()
+    {
+        return $this->fromEmailAddress;
+    }
+
+    /**
+     * @param mixed $fromEmailAddress
+     */
+    public function setFromEmailAddress($fromEmailAddress)
+    {
+        $this->fromEmailAddress = $fromEmailAddress;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getFromName()
+    {
+        return $this->fromName;
+    }
+
+    /**
+     * @param mixed $fromName
+     */
+    public function setFromName($fromName)
+    {
+        $this->fromName = $fromName;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getMemo()
+    {
+        return $this->memo;
+    }
+
+    /**
+     * @param mixed $memo
+     */
+    public function setMemo($memo)
+    {
+        if(strlen($memo) > 50) {
+            throw new \Exception('Memo should maximum be 50 chars');
+        }
+
+        $this->memo = $memo;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getSubject()
+    {
+        return $this->subject;
+    }
+
+    /**
+     * @param mixed $subject
+     */
+    public function setSubject($subject)
+    {
+        if(strlen($subject) > 50) {
+            throw new \Exception('Subject should maximum be 50 chars');
+        }
+
+        $this->subject = $subject;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getSubjectCode()
+    {
+        return $this->subjectCode;
+    }
+
+    /**
+     * @param mixed $subjectCode
+     */
+    public function setSubjectCode($subjectCode)
+    {
+        $this->subjectCode = $subjectCode;
+    }
+
+}

src/Ups/Entity/Notification.php

@@ -0,0 +1,85 @@
+<?php
+namespace Ups\Entity;
+
+use DOMDocument;
+use DOMElement;
+use Ups\NodeInterface;
+
+// @todo Extend with more notification options (e.g. VoiceMessage)
+class Notification implements NodeInterface
+{
+
+    /**
+     * @var
+     */
+    private $notificationCode;
+
+    /**
+     * @var
+     */
+    private $emailMessage;
+
+    /**
+     * Notification Codes from documentation
+     */
+    const CODE_RETURN_OR_LABEL_CREATION = '2'; // Only returns
+    const CODE_QV_IN_TRANSIT = '5'; // Only forward shipments
+    const CODE_QV_SHIP = '6'; // Only forward shipments
+    const CODE_QV_EXCEPTION = '7';
+    const CODE_QV_DELIVERY = '8';
+    const CODE_ALTERNATE_DELIVERY_LOCATION = '012';
+    const CODE_UAP_SHIPPER = '013';
+
+    /**
+     * @param null|DOMDocument $document
+     * @return DOMElement
+     */
+    public function toNode(DOMDocument $document = null)
+    {
+        if (null === $document) {
+            $document = new DOMDocument();
+        }
+
+        $node = $document->createElement('Notification');
+
+        $node->appendChild($document->createElement('NotificationCode', $this->getNotificationCode()));
+        if($this->getEmailMessage() !== null) {
+            $node->appendChild($this->emailMessage->toNode($document));
+        }
+
+        return $node;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getNotificationCode()
+    {
+        return $this->notificationCode;
+    }
+
+    /**
+     * @param mixed $notificationCode
+     */
+    public function setNotificationCode($notificationCode)
+    {
+        $this->notificationCode = $notificationCode;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getEmailMessage()
+    {
+        return $this->emailMessage;
+    }
+
+    /**
+     * @param mixed $emailMessage
+     */
+    public function setEmailMessage($emailMessage)
+    {
+        $this->emailMessage = $emailMessage;
+    }
+
+}

src/Ups/Entity/ShipmentServiceOptions.php

@@ -15,6 +15,7 @@ class ShipmentServiceOptions implements NodeInterface
     public $DirectDeliveryOnlyIndicator;
 
     private $internationalForms;
+    private $notifications = array();
 
     function __construct($response = null)
     {
@@ -70,6 +71,12 @@ public function toNode(DOMDocument $document = null)
             $node->appendChild($this->internationalForms->toNode($document));
         }
 
+        if(!empty($this->notifications)) {
+            foreach($this->notifications as $notification) {
+                $node->appendChild($notification->toNode($document));
+            }
+        }
+
         return $node;
     }
 
@@ -89,4 +96,26 @@ public function getInternationalForms()
         return $this->internationalForms;
     }
 
+    /**
+     * @param Notification $notification
+     */
+    public function addNotification(Notification $notification)
+    {
+        $this->notifications[] = $notification;
+
+        if(count($this->notifications) > 3) {
+            throw new \Exception('Maximum 3 notifications allowed');
+        }
+
+        return $this;
+    }
+
+    /**
+     * @return array
+     */
+    public function getNotifications()
+    {
+        return $this->notifications;
+    }
+
 }