ZF-8527: Adding the ability for Zend_Mail recipient functions to optionally take arrays of emails

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@19585 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Mail-AddingRecipients.xml

@@ -43,6 +43,17 @@
             brackets in the parameter.
         </para>
     </note>
+
+    <note>
+        <title>Optional Usage</title>
+
+        <para>
+            All three of these methods can also accept an array of email addresses
+            to add instead of one at a time.  In the case of <methodname>addTo()</methodname> and
+            <methodname>addCc()</methodname>, they can be associative arrays where the key is the
+            human readable name for the recipient.
+        </para>
+    </note>
 </sect1>
 <!--
 vim:se ts=4 sw=4 et:

library/Zend/Mail.php

@@ -528,44 +528,65 @@ class Zend_Mail extends Zend_Mime_Message
     }
 
     /**
-     * Adds To-header and recipient
+     * Adds To-header and recipient, $email can be an array, or a single string address
      *
-     * @param  string $email
+     * @param  string|array $email
      * @param  string $name
      * @return Zend_Mail Provides fluent interface
      */
     public function addTo($email, $name='')
     {
-        $this->_addRecipientAndHeader('To', $email, $name);
-        $this->_to[] = $email;
+        if (!is_array($email)) {
+            $email = array($name => $email);
+        }
+        
+        foreach ($email as $n => $recipient) {
+            $this->_addRecipientAndHeader('To', $recipient, is_int($n) ? '' : $n);
+            $this->_to[] = $recipient;
+        }
+
         return $this;
     }
 
     /**
-     * Adds Cc-header and recipient
+     * Adds Cc-header and recipient, $email can be an array, or a single string address
      *
-     * @param  string    $email
+     * @param  string|array    $email
      * @param  string    $name
      * @return Zend_Mail Provides fluent interface
      */
     public function addCc($email, $name='')
     {
-        $this->_addRecipientAndHeader('Cc', $email, $name);
+        if (!is_array($email)) {
+            $email = array($name => $email);
+        }
+        
+        foreach ($email as $n => $recipient) {
+            $this->_addRecipientAndHeader('Cc', $recipient, is_int($n) ? '' : $n);
+        }
+        
         return $this;
     }
 
     /**
-     * Adds Bcc recipient
+     * Adds Bcc recipient, $email can be an array, or a single string address
      *
-     * @param  string    $email
+     * @param  string|array    $email
      * @return Zend_Mail Provides fluent interface
      */
     public function addBcc($email)
     {
-        $this->_addRecipientAndHeader('Bcc', $email, '');
+        if (!is_array($email)) {
+            $email = array($email);
+        }
+        
+        foreach ($email as $recipient) {
+            $this->_addRecipientAndHeader('Bcc', $recipient, '');
+        }
+        
         return $this;
     }
-
+    
     /**
      * Return list of recipient email addresses
      *

tests/Zend/Mail/MailTest.php

@@ -159,6 +159,38 @@ class Zend_Mail_MailTest extends PHPUnit_Framework_TestCase
         $this->assertContains('To: recipient1@example.com', $mock->header);
         $this->assertContains('Cc: Example no. 1 for cc <recipient1_cc@example.com>', $mock->header);
     }
+    
+    /**
+     * Test sending in arrays of recipients
+     */
+    public function testArrayRecipients()
+    {
+        $mail = new Zend_Mail();
+        $res = $mail->setBodyText('Test #2');
+        $mail->setFrom('eli@example.com', 'test Mail User');
+        $mail->setSubject('Subject #2');
+        $mail->addTo(array('heather@example.com', 'Ramsey White' => 'ramsey@example.com'));
+        $mail->addCc(array('keith@example.com', 'Cal Evans' => 'cal@example.com'));
+        $mail->addBcc(array('ralph@example.com', 'matthew@example.com'));
+
+        $mock = new Zend_Mail_Transport_Mock();
+        $mail->send($mock);
+
+        $this->assertTrue($mock->called);
+        $this->assertEquals('eli@example.com', $mock->from);
+        $this->assertContains('heather@example.com', $mock->recipients);
+        $this->assertContains('ramsey@example.com', $mock->recipients);
+        $this->assertContains('ralph@example.com', $mock->recipients);
+        $this->assertContains('matthew@example.com', $mock->recipients);
+        $this->assertContains('keith@example.com', $mock->recipients);
+        $this->assertContains('cal@example.com', $mock->recipients);
+        $this->assertContains('Test #2', $mock->body);
+        $this->assertContains('From: test Mail User <eli@example.com>', $mock->header);
+        $this->assertContains('Subject: Subject #2', $mock->header);
+        $this->assertContains('To: heather@example.com', $mock->header);
+        $this->assertContains('Ramsey White <ramsey@example.com>', $mock->header);
+        $this->assertContains('Cal Evans <cal@example.com>', $mock->header);
+    }
 
     /**
      * Check if Header Fields are encoded correctly and if