Source for file mail.php

Documentation is available at mail.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  Mail
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die;
  11.  
  12. jimport('phpmailer.phpmailer');
  13.  
  14. /**
  15.  * Email Class.  Provides a common interface to send email from the Joomla! Platform
  16.  *
  17.  * @package     Joomla.Platform
  18.  * @subpackage  Mail
  19.  * @since       11.1
  20.  */
  21. class JMail extends PHPMailer
  22. {
  23.     /**
  24.      * @var    array  JMail instances container.
  25.      * @since  11.3
  26.      */
  27.     protected static $instances = array();
  28.  
  29.     /**
  30.      * @var    string  Charset of the message.
  31.      * @since  11.1
  32.      */
  33.     public $CharSet = 'utf-8';
  34.  
  35.     /**
  36.      * Constructor
  37.      *
  38.      * @since   11.1
  39.      */
  40.     public function __construct()
  41.     {
  42.         // PHPMailer has an issue using the relative path for its language files
  43.         $this->SetLanguage('joomla', JPATH_PLATFORM . '/phpmailer/language/');
  44.     }
  45.  
  46.     /**
  47.      * Returns the global email object, only creating it
  48.      * if it doesn't already exist.
  49.      *
  50.      * NOTE: If you need an instance to use that does not have the global configuration
  51.      * values, use an id string that is not 'Joomla'.
  52.      *
  53.      * @param   string  $id  The id string for the JMail instance [optional]
  54.      *
  55.      * @return  JMail  The global JMail object
  56.      *
  57.      * @since   11.1
  58.      */
  59.     public static function getInstance($id = 'Joomla')
  60.     {
  61.         if (empty(self::$instances[$id]))
  62.         {
  63.             self::$instances[$id] = new JMail;
  64.         }
  65.  
  66.         return self::$instances[$id];
  67.     }
  68.  
  69.     /**
  70.      * Send the mail
  71.      *
  72.      * @return  mixed  True if successful; JError if using legacy tree (no exception thrown in that case).
  73.      *
  74.      * @since   11.1
  75.      * @throws  RuntimeException
  76.      */
  77.     public function Send()
  78.     {
  79.         if (JFactory::getConfig()->get('mailonline'))
  80.         {
  81.             if (($this->Mailer == 'mail') && !function_exists('mail'))
  82.             {
  83.                 if (class_exists('JError'))
  84.                 {
  85.                     return JError::raiseNotice(500, JText::_('JLIB_MAIL_FUNCTION_DISABLED'));
  86.                 }
  87.                 else
  88.                 {
  89.                     throw new RuntimeException(sprintf('%s::Send mail not enabled.', get_class($this)));
  90.                 }
  91.             }
  92.  
  93.             @$result = parent::Send();
  94.  
  95.             if ($result == false)
  96.             {
  97.                 if (class_exists('JError'))
  98.                 {
  99.                     $result = JError::raiseNotice(500, JText::_($this->ErrorInfo));
  100.                 }
  101.                 else
  102.                 {
  103.                     throw new RuntimeException(sprintf('%s::Send failed: "%s".', get_class($this), $this->ErrorInfo));
  104.                 }
  105.             }
  106.  
  107.             return $result;
  108.         }
  109.         else
  110.         {
  111.             JFactory::getApplication()->enqueueMessage(JText::_('JLIB_MAIL_FUNCTION_OFFLINE'));
  112.  
  113.             return false;
  114.         }
  115.     }
  116.  
  117.     /**
  118.      * Set the email sender
  119.      *
  120.      * @param   mixed  $from  email address and Name of sender
  121.      *                         <code>array([0] => email Address, [1] => Name)</code>
  122.      *                         or as a string
  123.      *
  124.      * @return  JMail  Returns this object for chaining.
  125.      *
  126.      * @since   11.1
  127.      * @throws  UnexpectedValueException
  128.      */
  129.     public function setSender($from)
  130.     {
  131.         if (is_array($from))
  132.         {
  133.             // If $from is an array we assume it has an address and a name
  134.             if (isset($from[2]))
  135.             {
  136.                 // If it is an array with entries, use them
  137.                 $this->SetFrom(JMailHelper::cleanLine($from[0]), JMailHelper::cleanLine($from[1]), (bool) $from[2]);
  138.             }
  139.             else
  140.             {
  141.                 $this->SetFrom(JMailHelper::cleanLine($from[0]), JMailHelper::cleanLine($from[1]));
  142.             }
  143.         }
  144.         elseif (is_string($from))
  145.         {
  146.             // If it is a string we assume it is just the address
  147.             $this->SetFrom(JMailHelper::cleanLine($from));
  148.         }
  149.         else
  150.         {
  151.             // If it is neither, we log a message and throw an exception
  152.             JLog::add(JText::sprintf('JLIB_MAIL_INVALID_EMAIL_SENDER', $from), JLog::WARNING, 'jerror');
  153.  
  154.             throw new UnexpectedValueException(sprintf('Invalid email Sender: %s, JMail::setSender(%s)', $from));
  155.         }
  156.  
  157.         return $this;
  158.     }
  159.  
  160.     /**
  161.      * Set the email subject
  162.      *
  163.      * @param   string  $subject  Subject of the email
  164.      *
  165.      * @return  JMail  Returns this object for chaining.
  166.      *
  167.      * @since   11.1
  168.      */
  169.     public function setSubject($subject)
  170.     {
  171.         $this->Subject = JMailHelper::cleanLine($subject);
  172.  
  173.         return $this;
  174.     }
  175.  
  176.     /**
  177.      * Set the email body
  178.      *
  179.      * @param   string  $content  Body of the email
  180.      *
  181.      * @return  JMail  Returns this object for chaining.
  182.      *
  183.      * @since   11.1
  184.      */
  185.     public function setBody($content)
  186.     {
  187.         /*
  188.          * Filter the Body
  189.          * TODO: Check for XSS
  190.          */
  191.         $this->Body = JMailHelper::cleanText($content);
  192.  
  193.         return $this;
  194.     }
  195.  
  196.     /**
  197.      * Add recipients to the email.
  198.      *
  199.      * @param   mixed   $recipient  Either a string or array of strings [email address(es)]
  200.      * @param   mixed   $name       Either a string or array of strings [name(s)]
  201.      * @param   string  $method     The parent method's name.
  202.      *
  203.      * @return  JMail  Returns this object for chaining.
  204.      *
  205.      * @since   11.1
  206.      * @throws  InvalidArgumentException
  207.      */
  208.     protected function add($recipient, $name = '', $method = 'AddAddress')
  209.     {
  210.         // If the recipient is an array, add each recipient... otherwise just add the one
  211.         if (is_array($recipient))
  212.         {
  213.             if (is_array($name))
  214.             {
  215.                 $combined = array_combine($recipient, $name);
  216.  
  217.                 if ($combined === false)
  218.                 {
  219.                     throw new InvalidArgumentException("The number of elements for each array isn't equal.");
  220.                 }
  221.  
  222.                 foreach ($combined as $recipientEmail => $recipientName)
  223.                 {
  224.                     $recipientEmail = JMailHelper::cleanLine($recipientEmail);
  225.                     $recipientName = JMailHelper::cleanLine($recipientName);
  226.                     call_user_func('parent::' . $method, $recipientEmail, $recipientName);
  227.                 }
  228.             }
  229.             else
  230.             {
  231.                 $name = JMailHelper::cleanLine($name);
  232.  
  233.                 foreach ($recipient as $to)
  234.                 {
  235.                     $to = JMailHelper::cleanLine($to);
  236.                     call_user_func('parent::' . $method, $to, $name);
  237.                 }
  238.             }
  239.         }
  240.         else
  241.         {
  242.             $recipient = JMailHelper::cleanLine($recipient);
  243.             call_user_func('parent::' . $method, $recipient, $name);
  244.         }
  245.  
  246.         return $this;
  247.     }
  248.  
  249.     /**
  250.      * Add recipients to the email
  251.      *
  252.      * @param   mixed  $recipient  Either a string or array of strings [email address(es)]
  253.      * @param   mixed  $name       Either a string or array of strings [name(s)]
  254.      *
  255.      * @return  JMail  Returns this object for chaining.
  256.      *
  257.      * @since   11.1
  258.      */
  259.     public function addRecipient($recipient, $name = '')
  260.     {
  261.         $this->add($recipient, $name, 'AddAddress');
  262.  
  263.         return $this;
  264.     }
  265.  
  266.     /**
  267.      * Add carbon copy recipients to the email
  268.      *
  269.      * @param   mixed  $cc    Either a string or array of strings [email address(es)]
  270.      * @param   mixed  $name  Either a string or array of strings [name(s)]
  271.      *
  272.      * @return  JMail  Returns this object for chaining.
  273.      *
  274.      * @since   11.1
  275.      */
  276.     public function addCC($cc, $name = '')
  277.     {
  278.         // If the carbon copy recipient is an array, add each recipient... otherwise just add the one
  279.         if (isset($cc))
  280.         {
  281.             $this->add($cc, $name, 'AddCC');
  282.         }
  283.  
  284.         return $this;
  285.     }
  286.  
  287.     /**
  288.      * Add blind carbon copy recipients to the email
  289.      *
  290.      * @param   mixed  $bcc   Either a string or array of strings [email address(es)]
  291.      * @param   mixed  $name  Either a string or array of strings [name(s)]
  292.      *
  293.      * @return  JMail  Returns this object for chaining.
  294.      *
  295.      * @since   11.1
  296.      */
  297.     public function addBCC($bcc, $name = '')
  298.     {
  299.         // If the blind carbon copy recipient is an array, add each recipient... otherwise just add the one
  300.         if (isset($bcc))
  301.         {
  302.             $this->add($bcc, $name, 'AddBCC');
  303.         }
  304.  
  305.         return $this;
  306.     }
  307.  
  308.     /**
  309.      * Add file attachments to the email
  310.      *
  311.      * @param   mixed  $attachment  Either a string or array of strings [filenames]
  312.      * @param   mixed  $name        Either a string or array of strings [names]
  313.      * @param   mixed  $encoding    The encoding of the attachment
  314.      * @param   mixed  $type        The mime type
  315.      *
  316.      * @return  JMail  Returns this object for chaining.
  317.      *
  318.      * @since   12.2
  319.      * @throws  InvalidArgumentException
  320.      */
  321.     public function addAttachment($attachment, $name = '', $encoding = 'base64', $type = 'application/octet-stream')
  322.     {
  323.         // If the file attachments is an array, add each file... otherwise just add the one
  324.         if (isset($attachment))
  325.         {
  326.             if (is_array($attachment))
  327.             {
  328.                 if (!empty($name) && count($attachment) != count($name))
  329.                 {
  330.                     throw new InvalidArgumentException("The number of attachments must be equal with the number of name");
  331.                 }
  332.  
  333.                 foreach ($attachment as $key => $file)
  334.                 {
  335.                     if (!empty($name))
  336.                     {
  337.                         parent::AddAttachment($file, $name[$key], $encoding, $type);
  338.                     }
  339.                     else
  340.                     {
  341.                         parent::AddAttachment($file, $name, $encoding, $type);
  342.                     }
  343.                 }
  344.             }
  345.             else
  346.             {
  347.                 parent::AddAttachment($attachment, $name, $encoding, $type);
  348.             }
  349.         }
  350.  
  351.         return $this;
  352.     }
  353.  
  354.     /**
  355.      * Add Reply to email address(es) to the email
  356.      *
  357.      * @param   mixed  $replyto  Either a string or array of strings [email address(es)]
  358.      * @param   mixed  $name     Either a string or array of strings [name(s)]
  359.      *
  360.      * @return  JMail  Returns this object for chaining.
  361.      *
  362.      * @since   11.1
  363.      */
  364.     public function addReplyTo($replyto, $name = '')
  365.     {
  366.         $this->add($replyto, $name, 'AddReplyTo');
  367.  
  368.         return $this;
  369.     }
  370.  
  371.     /**
  372.      * Sets message type to HTML
  373.      *
  374.      * @param   boolean  $ishtml  Boolean true or false.
  375.      *
  376.      * @return  JMail  Returns this object for chaining.
  377.      *
  378.      * @since   12.3
  379.      */
  380.     public function isHtml($ishtml = true)
  381.     {
  382.         parent::IsHTML($ishtml);
  383.  
  384.         return $this;
  385.     }
  386.  
  387.     /**
  388.      * Use sendmail for sending the email
  389.      *
  390.      * @param   string  $sendmail  Path to sendmail [optional]
  391.      *
  392.      * @return  boolean  True on success
  393.      *
  394.      * @since   11.1
  395.      */
  396.     public function useSendmail($sendmail = null)
  397.     {
  398.         $this->Sendmail = $sendmail;
  399.  
  400.         if (!empty($this->Sendmail))
  401.         {
  402.             $this->IsSendmail();
  403.  
  404.             return true;
  405.         }
  406.         else
  407.         {
  408.             $this->IsMail();
  409.  
  410.             return false;
  411.         }
  412.     }
  413.  
  414.     /**
  415.      * Use SMTP for sending the email
  416.      *
  417.      * @param   string   $auth    SMTP Authentication [optional]
  418.      * @param   string   $host    SMTP Host [optional]
  419.      * @param   string   $user    SMTP Username [optional]
  420.      * @param   string   $pass    SMTP Password [optional]
  421.      * @param   string   $secure  Use secure methods
  422.      * @param   integer  $port    The SMTP port
  423.      *
  424.      * @return  boolean  True on success
  425.      *
  426.      * @since   11.1
  427.      */
  428.     public function useSMTP($auth = null, $host = null, $user = null, $pass = null, $secure = null, $port = 25)
  429.     {
  430.         $this->SMTPAuth = $auth;
  431.         $this->Host = $host;
  432.         $this->Username = $user;
  433.         $this->Password = $pass;
  434.         $this->Port = $port;
  435.  
  436.         if ($secure == 'ssl' || $secure == 'tls')
  437.         {
  438.             $this->SMTPSecure = $secure;
  439.         }
  440.  
  441.         if (($this->SMTPAuth !== null && $this->Host !== null && $this->Username !== null && $this->Password !== null)
  442.             || ($this->SMTPAuth === null && $this->Host !== null))
  443.         {
  444.             $this->IsSMTP();
  445.  
  446.             return true;
  447.         }
  448.         else
  449.         {
  450.             $this->IsMail();
  451.  
  452.             return false;
  453.         }
  454.     }
  455.  
  456.     /**
  457.      * Function to send an email
  458.      *
  459.      * @param   string   $from         From email address
  460.      * @param   string   $fromName     From name
  461.      * @param   mixed    $recipient    Recipient email address(es)
  462.      * @param   string   $subject      email subject
  463.      * @param   string   $body         Message body
  464.      * @param   boolean  $mode         false = plain text, true = HTML
  465.      * @param   mixed    $cc           CC email address(es)
  466.      * @param   mixed    $bcc          BCC email address(es)
  467.      * @param   mixed    $attachment   Attachment file name(s)
  468.      * @param   mixed    $replyTo      Reply to email address(es)
  469.      * @param   mixed    $replyToName  Reply to name(s)
  470.      *
  471.      * @return  boolean  True on success
  472.      *
  473.      * @since   11.1
  474.      */
  475.     public function sendMail($from, $fromName, $recipient, $subject, $body, $mode = false, $cc = null, $bcc = null, $attachment = null,
  476.         $replyTo = null, $replyToName = null)
  477.     {
  478.         $this->setSubject($subject);
  479.         $this->setBody($body);
  480.  
  481.         // Are we sending the email as HTML?
  482.         if ($mode)
  483.         {
  484.             $this->IsHTML(true);
  485.         }
  486.  
  487.         $this->addRecipient($recipient);
  488.         $this->addCC($cc);
  489.         $this->addBCC($bcc);
  490.         $this->addAttachment($attachment);
  491.  
  492.         // Take care of reply email addresses
  493.         if (is_array($replyTo))
  494.         {
  495.             $numReplyTo = count($replyTo);
  496.  
  497.             for ($i = 0; $i < $numReplyTo; $i++)
  498.             {
  499.                 $this->addReplyTo(array($replyTo[$i], $replyToName[$i]));
  500.             }
  501.         }
  502.         elseif (isset($replyTo))
  503.         {
  504.             $this->addReplyTo(array($replyTo, $replyToName));
  505.         }
  506.  
  507.         // Add sender to replyTo only if no replyTo received
  508.         $autoReplyTo = (empty($this->ReplyTo)) ? true : false;
  509.         $this->setSender(array($from, $fromName, $autoReplyTo));
  510.  
  511.         return $this->Send();
  512.     }
  513.  
  514.     /**
  515.      * Sends mail to administrator for approval of a user submission
  516.      *
  517.      * @param   string  $adminName   Name of administrator
  518.      * @param   string  $adminEmail  Email address of administrator
  519.      * @param   string  $email       [NOT USED TODO: Deprecate?]
  520.      * @param   string  $type        Type of item to approve
  521.      * @param   string  $title       Title of item to approve
  522.      * @param   string  $author      Author of item to approve
  523.      * @param   string  $url         A URL to included in the mail
  524.      *
  525.      * @return  boolean  True on success
  526.      *
  527.      * @since   11.1
  528.      */
  529.     public function sendAdminMail($adminName, $adminEmail, $email, $type, $title, $author, $url = null)
  530.     {
  531.         $subject = JText::sprintf('JLIB_MAIL_USER_SUBMITTED', $type);
  532.  
  533.         $message = sprintf(JText::_('JLIB_MAIL_MSG_ADMIN'), $adminName, $type, $title, $author, $url, $url, 'administrator', $type);
  534.         $message .= JText::_('JLIB_MAIL_MSG') . "\n";
  535.  
  536.         $this->addRecipient($adminEmail);
  537.         $this->setSubject($subject);
  538.         $this->setBody($message);
  539.  
  540.         return $this->Send();
  541.     }
  542. }

Documentation generated on Tue, 19 Nov 2013 15:07:30 +0100 by phpDocumentor 1.4.3