Updating Mail and also breaking the API to make some significant changes

diff --git a/dev/changes.txt b/dev/changes.txt
index c5ee9a30f4bd1a13a9fba003e35d457638b11a4b..274bad011b91a904490c84cbe9a199bbcf17a103 100644 (file)
--- a/dev/changes.txt
+++ b/dev/changes.txt
@@ -4,6 +4,7 @@
 - ** API BRAEK ** removed the tag handler feature of the XML processor
 - ** API BREAK ** removed the localization module
 - Use gettext internally for strings
+- Completely changed external Mail API to make sending emails more developer-friendly
 
 2.0.2
 ===============

diff --git a/mail.php b/mail.php
index af114b30a5908d9a9c60cd5d4e96f080c63a9489..6bb11fb1174d067531c62e9765d5018146599655 100644 (file)
--- a/mail.php
+++ b/mail.php
@@ -47,13 +47,6 @@ class Mail
        */
        var $registry = null;
        
-       /**
-       * The message recipient's email address in the form of array(email => name)
-       * @var  array
-       * @access       private
-       */
-       var $to = array();
-       
        /**
        * The subject of the message
        * @var  string
@@ -117,23 +110,6 @@ class Mail
        */
        var $charset = 'utf-8'; // should we be using iso-8859-1 ?
        
-       /**
-       * Fields array that is used in this module
-       * @var  array
-       * @access       private
-       */
-       var $fields = array(
-               'subject'       => array(REQ_YES,       null,   false),
-               'bodytext'      => array(REQ_YES,       null,   false),
-               'bodyhtml'      => array(REQ_NO,        null,   false),
-               'from'          => array(REQ_YES,       null,   false),
-               'fromname'      => array(REQ_NO,        null,   false),
-               'headers'       => array(REQ_NO,        null,   false),
-               'sendhtml'      => array(REQ_NO,        null,   false),
-               'delim'         => array(REQ_YES,       null,   true),
-               'charset'       => array(REQ_YES,       null,   true)
-       );
-       
        // ###################################################################
        /**
        * Constructor
@@ -154,93 +130,95 @@ class Mail
        
        // ###################################################################
        /**
-       * Sets an ISSO field
+       * Sets the subject
        *
        * @access       public
        *
-       * @param        string  Field name
-       * @param        mixed   Value of the field
+       * @param        string  Subject text
        */
-       function set($name, $value)
+       function setSubject($subject)
        {
-               if (empty($value) AND $this->fields["$name"][0] == REQ_YES)
-               {
-                       trigger_error('Field ' . $name . ' cannot be empty', E_USER_ERROR);
-               }
-               
-               $this->registry->do_set($name, $value, 'mail');
+               $this->subject = $subject;
        }
        
        // ###################################################################
        /**
-       * Gets an ISSO field
+       * Sets the body text (required)
        *
        * @access       public
        *
-       * @param        string  Field name
+       * @param        string  Body text
+       */
+       function setBodyText($body)
+       {
+               $this->bodytext = $body;
+       }
+       
+       // ###################################################################
+       /**
+       * Sets the HTML body (optional)
        *
-       * @return       mixed   Value of the field
+       * @access       public
+       *
+       * @param        string  Body HTML
        */
-       function get($fieldname)
+       function setBodyHtml($body)
        {
-               return $this->registry->do_get($fieldname, 'mail');
+               $this->bodyhtml = $body;
        }
        
        // ###################################################################
        /**
-       * Adds a to address
+       * Sets the from address
        *
        * @access       public
        *
-       * @param        string  Name to send to
-       * @param        string  Email address
+       * @param        string  Sending email address
        */
-       function to_add($name, $address)
+       function setFromAddress($address)
        {
-               if (isset($this->to["$address"]) AND $name !== null)
-               {
-                       return;
-               }
-               
-               if ($this->registry->modules['functions']->is_valid_email($address))
-               {
-                       $this->to["$address"] = $name;
-               }
+               $this->from = $address;
        }
        
        // ###################################################################
        /**
-       * Removes a to address by email; if FALSE, it will clear the array
+       * Sets the from display name
        *
        * @access       public
        *
-       * @param        string  Email address to remove, or FALSE to clear array
+       * @param        string  From name
        */
-       function to_remove($address)
+       function setFromName($name)
        {
-               if ($address === false)
-               {
-                       $this->to = array();
-               }
-               else
-               {
-                       unset($this->to["$address"]);
-               }
+               $this->fromname = $name;
        }
        
        // ###################################################################
        /**
-       * Returns the list of "to" addresses
+       * Sets any additional headers
        *
        * @access       public
        *
-       * @return       array   List of to-addresses
+       * @param        string  Additional headers separated by a \n
        */
-       function to_fetch()
-       {               
-               return $this->to;
+       function setHeaders($headers)
+       {
+               $this->headers = $headers;
        }
        
+       // ###################################################################
+       /**
+       * Sets the character set to send the email in
+       *
+       * @access       public
+       *
+       * @param        string  Charset
+       */
+       function setCharset($charset)
+       {
+               $this->charset = $charset;
+       }
+               
        // ###################################################################
        /**
        * Sends an email to the specified address with the specified
@@ -248,17 +226,17 @@ class Mail
        *
        * @access       public
        *
-       * @param        bool    Clear the "to" list after sending?
+       * @param        string  Email address to send to
+       * @param        string  Name of the recipient
+       * @param        bool    Send an HTML multipart (if HTML body specified)?
        *
        * @return       bool    Status of the message
        */
-       function send($cleartos = false)
+       function send($address, $name = null, $sendhtml = false)
        {
-               // check the required stuff
-               $this->registry->check_isso_fields(get_class($this));
-               if (sizeof($this->to) < 1)
+               if (empty($email))
                {
-                       trigger_error('You need at least one email address to send to', E_USER_ERROR);
+                       trigger_error('You need to specify an email address', E_USER_ERROR);
                        return false;
                }
                
@@ -271,23 +249,11 @@ class Mail
                }
                
                // sort out the to addresses
-               $tolist = array();
-               foreach ($this->to AS $address => $name)
-               {
-                       $address = $this->_fetch_first_line($address);
-                       $address = trim($this->registry->unsanitize($address));
-                       $name = $this->_fetch_first_line($name);
-                       $name = trim($this->registry->unsanitize($name));
-                       
-                       if ($name == null)
-                       {
-                               $tolist[] = $address;
-                       }
-                       else
-                       {
-                               $tolist[] = "\"$name\" <$address>";
-                       }
-               }
+               $address = $this->_fetch_first_line($address);
+               $address = trim($this->registry->unsanitize($address));
+               $name = $this->_fetch_first_line($name);
+               $name = trim($this->registry->unsanitize($name));
+               $tostring = ($name == null ?  $address : "\"$name\" <$address>");
                
                // sanitize the from field
                $this->from = $this->_fetch_first_line($this->from);
@@ -313,7 +279,7 @@ class Mail
                $this->headers .= "MIME-Version: 1.0" . $this->delim;
                
                // see if we need to use mime/multipart
-               if ($this->sendhtml AND $this->fields['bodyhtml'][2] == true)
+               if ($sendhtml AND $this->fields['bodyhtml'][2] == true)
                {
                        $boundary = 'ISSO-MULTIPART-' . $this->registry->modules['functions']->rand(10);
                        $this->headers .= "Content-Type: multipart/alternative; boundary=\"$boundary\"" . $this->delim;
@@ -347,21 +313,13 @@ class Mail
                $this->headers = trim($this->headers);
                
                // attempt to send the mail!
-               foreach ($tolist AS $address)
+               if (mail($tostring, $this->subject, $body, $this->headers, "-f {$this->from}"))
                {
-                       if (mail($address, $this->subject, $body, $this->headers, "-f {$this->from}"))
-                       {
-                               $this->registry->debug("email: sent to $address");
-                       }
-                       else
-                       {
-                               $this->registry->debug("email: error sending to $address");
-                       }
+                       $this->registry->debug("email: sent to $address");
                }
-               
-               if ($cleartos)
+               else
                {
-                       $this->to = array();
+                       $this->registry->debug("email: error sending to $address");
                }
        }