Releasing 1.0.2

Author: technicalguru

README.md

@@ -377,6 +377,11 @@ $bccConfig     = BccConfig::from($jsonStringOrObjectOrAssocArray);
 $emailConfig   = EmailConfig::from($jsonStringOrObjectOrAssocArray);
 ```
 
+## Sending and queueing multiple e-mails
+
+It is possible to pass an array of `Email` objects to `send()` and `queue()` functions. However, especially for sending
+e-mails immediately you should be aware that this can take some time. A better strategy is to queue mass mailings.
+
 # Development Notes
 
 Most PHPUnit tests will not be executed when there is no SMTP server or database available. The unit tests will check

src/TgEmail/EmailAddress.php

@@ -55,20 +55,24 @@ public function __toString() {
     public static function from($s, $name = NULL) {
         if (is_string($s)) {
             if ($name == NULL) {
-                $pos = strpos($s, '<');
-                if ($pos !== FALSE) {
-                    $name = $pos > 0 ? trim(substr($s, 0, $pos)) : NULL;
-                    if ($name == '') $name = NULL;
+				if (substr($s, 0, 1) == '{') {
+					return self::from(json_decode($s));
+				} else {
+					$pos = strpos($s, '<');
+					if ($pos !== FALSE) {
+						$name = $pos > 0 ? trim(substr($s, 0, $pos)) : NULL;
+						if ($name == '') $name = NULL;
 
-                    $email = substr($s, $pos + 1);
-                    $pos = strpos($email, '>');
-                    if ($pos !== FALSE) {
-                        $email = trim(substr($email, 0, $pos));
-                    }
+						$email = substr($s, $pos + 1);
+						$pos = strpos($email, '>');
+						if ($pos !== FALSE) {
+							$email = trim(substr($email, 0, $pos));
+						}
 
-                    return new EmailAddress($email, $name);
-                }
-                return new EmailAddress($s);
+						return new EmailAddress($email, $name);
+					}
+					return new EmailAddress($s);
+				}
             } else {
                 return new EmailAddress($s, $name);
             }

src/TgEmail/EmailQueue.php

@@ -64,35 +64,6 @@ public function setMailMode($mailMode, $config = NULL) {
         $this->config->setMailMode($mailMode, $config);
     }
 
-    /**
-     * TODO: smth like queue($email, $recipients) ?
-     * Sends multiple emails.
-     *
-     * @param
-     *            array of
-     *            mixed recipients - array of recipients or single recipient to send to
-     *            string templateName - mail template name to be used, located in <component>/site/email/<lang>/<name>.[html|txt].php
-     *            string subject - subject
-     *            mixed params - parameters to be given to email template
-     *            string domain - the domain this mail belongs to
-     * @return array of
-     *         boolean success - overall success
-     *         array errors - individual boolean return codes for each mail
-     *
-    public function queueMails($mailInfos) {
-        $rc = array(
-            'success' => true,
-            'errors' => array(),
-        );
-        foreach ($mailInfos as $mail) {
-            $c = $this->queueMail($mail['recipients'], $mail['templateName'], $mail['subject'], $mail['params']);
-            $rc['error'][] = $c;
-            if (! $c) $rc['success'] = false;
-        }
-        return $rc;
-    }
-    */
-    
     protected function getMailer() {
         if ($this->mailer == null) {
             $this->mailer = new PHPMailer();
@@ -226,10 +197,25 @@ public function getReconfiguredEmail(Email $email) {
         return $rc;
     }
 
-    public function send(Email $email) {
-        // Modify mail according to sending mode
-        $email = $this->getReconfiguredEmail($email);
-        return $this->_send($email);
+    /**
+     * Sends a single email or multiple emails.
+     * @param mixed $email - single Email object or array of Email objects
+     * @return TRUE when email was sent or number of emails sent successfully
+     */
+    public function send($email) {
+        if (is_a($email, 'TgEmail\\Email')) {
+            // Modify mail according to sending mode
+            $email = $this->getReconfiguredEmail($email);
+            return $this->_send($email);
+        } else if (is_array($email)) {
+            $sent = 0;
+            foreach ($email AS $m) {
+                if ($this->send($m)) $sent++;
+            }
+            return $sent;
+        } else {
+            throw new EmailException('Cannot send: $email must be array of Email or single Email object');
+        }
     }
 
     /**
@@ -298,10 +284,53 @@ protected function _send(Email $email) {
         return $rc;
     }
 
-    public function queue(Email $email) {
-        // Modify mail according to sending mode
-        $email = $this->getReconfiguredEmail($email);
-        return $this->_queue($email);
+    /**
+     * Queues a single email or multiple emails.
+     * <p>The second parameter $recipients can be used with single Email object only.</p>
+     * <p>Example of $recpients:</p>
+     * <ul>
+     * <li>list of list of recipients: <code>[ ["john.doe@example.com","john@example.com"], ["jane.doe@example.com"] ]</code></li>
+     * <li>list of recipient objects: <code>[ {"to":"john.doe@example.com", "cc":"jane.doe@example.com"}, ... ]</code></li>
+     * </ul>
+     * @param mixed $email - single Email object or array of Email objects
+     * @param array $recipients - list of recipients to send the same email. Can be a list of lists (TO addresses)
+     *    or a list of objects with to, cc or bcc attributes that define the recipients.
+     * @return TRUE when email was queued or number of emails queued successfully
+     */
+    public function queue($email, $recipients = NULL) {
+        if (is_a($email, 'TgEmail\\Email')) {
+            if ($recipients == NULL) {
+                // Single Email to be sent
+                // Modify mail according to sending mode
+                $email = $this->getReconfiguredEmail($email);
+                return $this->_queue($email);
+            }
+            // Single email with multiple recipient definitions
+            $queued = 0;
+            foreach ($recipients AS $def) {
+                if (is_array($def)) {
+                    // All TO addresses
+                    $email->recipients = NULL;
+                    $email->addTo($def);
+                    if ($this->queue($email)) $queued++;
+                } else {
+                    $email->recipients = NULL;
+                    if (isset($def->to))  $email->addTo($def->to);
+                    if (isset($def->cc))  $email->addCc($def->cc);
+                    if (isset($def->bcc)) $email->addBcc($def->bcc);
+                    if ($this->queue($email)) $queued++;
+                }
+            }
+            return $queued;
+        } else if (is_array($email)) {
+            $queued = 0;
+            foreach ($email AS $m) {
+                if ($this->queue($m)) $queued++;
+            }
+            return $queued;
+        } else {
+            throw new EmailException('Cannot queue: $email must be array of Email or single Email object');
+        }
     }
 
     /**

test.sh

@@ -0,0 +1,3 @@
+
+vendor/phpunit/phpunit/phpunit tests/
+

tests/TgEmail/EmailAddressTest.php

@@ -37,6 +37,11 @@ public function testFromWithString(): void {
         $this->assertEquals('John Doe <john.doe@example.com>', $addr->__toString());
     }
 
+    public function testFromWithJsonString(): void {
+        $addr = EmailAddress::from('{"name":"John Doe","email":"john.doe@example.com"}');
+        $this->assertEquals('John Doe <john.doe@example.com>', $addr->__toString());
+    }
+    
     public function testFromWithEmailName(): void {
         $addr = EmailAddress::from('john.doe@example.com', 'John Doe');
         $this->assertEquals('John Doe <john.doe@example.com>', $addr->__toString());