Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

Developer Network License

The Joomla! Developer Network content is © copyright 2006 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5
Source code for file /joomla/utilities/mail.php

Documentation is available at mail.php

  1. <?php
  2. /**
  3.  * @version        $Id: mail.php 6649 2007-02-17 07:23:48Z tcp $
  4.  * @package        Joomla.Framework
  5.  * @subpackage    Utilities
  6.  * @copyright    Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
  7.  * @license        GNU/GPL, see LICENSE.php
  8.  *  Joomla! is free software. This version may have been modified pursuant
  9.  *  to the GNU General Public License, and as distributed it includes or
  10.  *  is derivative of works licensed under the GNU General Public License or
  11.  *  other free or open source software licenses.
  12.  *  See COPYRIGHT.php for copyright notices and details.
  13.  */
  14.  
  15. // Check to ensure this file is within the rest of the framework
  16. defined('JPATH_BASE') or die();
  17.  
  18. jimport('phpmailer.phpmailer');
  19.  
  20. /**
  21.  * E-Mail Class.  Provides a common interface to send e-mail from the Joomla! Framework
  22.  *
  23.  * @author        Louis Landry <[email protected]>
  24.  * @package     Joomla.Framework
  25.  * @subpackage        Utilities
  26.  * @since        1.5
  27.  */
  28. class JMail extends PHPMailer
  29. {
  30.  
  31.     /**
  32.      * Constructor
  33.      *
  34.      */
  35.     function JMail()
  36.     {
  37.          // phpmailer has an issue using the relative path for it's language files
  38.          $this->SetLanguage('en', JPATH_LIBRARIES . '/phpmailer/language/');
  39.     }
  40.  
  41.     /**
  42.      * Returns a reference to a global e-mail object, only creating it
  43.      * if it doesn't already exist.
  44.      *
  45.      * This method must be invoked as:
  46.      *         <pre>  $mail =& JMail::getInstance();</pre>
  47.      *
  48.      * NOTE: If you need an instance to use that does not have the global configuration
  49.      * values, use an id string that is not 'Joomla'.
  50.      *
  51.      * @static
  52.      * @access public
  53.      * @param string $id The id string for the JMail instance [optional]
  54.      * @return object The global JMail object
  55.      * @since 1.5
  56.      */
  57.     function & getInstance($id = 'Joomla')
  58.     {
  59.         static $instances;
  60.  
  61.         if (!isset ($instances)) {
  62.             $instances = array ();
  63.         }
  64.  
  65.         if (empty ($instances[$id])) {
  66.             $instances[$id] = new JMail();
  67.         }
  68.  
  69.         return $instances[$id];
  70.     }
  71.  
  72.     /**
  73.      * @return mixed True if successful, a JError object otherwise
  74.      */
  75.     function &Send()
  76.     {
  77.         @ $result = parent::Send();
  78.  
  79.         if ($result == false)
  80.         {
  81.             // TODO: Set an appropriate error number
  82.             $result =& JError::raiseNotice( 500, $this->ErrorInfo );
  83.         }
  84.         return $result;
  85.     }
  86.  
  87.     /**
  88.      * Set the E-Mail sender
  89.      *
  90.      * @access public
  91.      * @param array $from E-Mail address and Name of sender
  92.      *          <pre>
  93.      *              array( [0] => E-Mail Address [1] => Name )
  94.      *          </pre>
  95.      * @return void 
  96.      * @since 1.5
  97.      */
  98.     function setSender($from)
  99.     {
  100.         // If $from is an array we assume it has an address and a name
  101.         if (is_array($from))
  102.         {
  103.             $this->From     = JMailHelper::cleanLine( $from[0] );
  104.             $this->FromName = JMailHelper::cleanLine( $from[1] );
  105.         // If it is a string we assume it is just the address
  106.         } elseif (is_string($from)) {
  107.             $this->From = JMailHelper::cleanLine( $from );
  108.         // If it is neither, we throw a warning
  109.         } else {
  110.             JError::raiseWarning( 0, "JMail::  Invalid E-Mail Sender: $from", "JMail::setSender($from)");
  111.         }
  112.     }
  113.  
  114.     /**
  115.      * Set the E-Mail subject
  116.      *
  117.      * @access public
  118.      * @param string $subject Subject of the e-mail
  119.      * @return void 
  120.      * @since 1.5
  121.      */
  122.     function setSubject($subject) {
  123.         $this->Subject = JMailHelper::cleanLine( $subject );
  124.     }
  125.  
  126.     /**
  127.      * Set the E-Mail body
  128.      *
  129.      * @access public
  130.      * @param string $content Body of the e-mail
  131.      * @return void 
  132.      * @since 1.5
  133.      */
  134.     function setBody($content)
  135.     {
  136.         /*
  137.          * Filter the Body
  138.          * TODO: Check for XSS
  139.          */
  140.         $this->Body = JMailHelper::cleanText( $content );
  141.     }
  142.  
  143.     /**
  144.      * Add recipients to the email
  145.      *
  146.      * @access public
  147.      * @param mixed $recipient Either a string or array of strings [e-mail address(es)]
  148.      * @return void 
  149.      * @since 1.5
  150.      */
  151.     function addRecipient($recipient)
  152.     {
  153.         // If the recipient is an aray, add each recipient... otherwise just add the one
  154.         if (is_array($recipient))
  155.         {
  156.             foreach ($recipient as $to) {
  157.                 $to = JMailHelper::cleanLine( $to );
  158.                 $this->AddAddress($to);
  159.             }
  160.         } else {
  161.             $recipient = JMailHelper::cleanLine( $recipient );
  162.             $this->AddAddress($recipient);
  163.         }
  164.     }
  165.  
  166.     /**
  167.      * Add carbon copy recipients to the email
  168.      *
  169.      * @access public
  170.      * @param mixed $cc Either a string or array of strings [e-mail address(es)]
  171.      * @return void 
  172.      * @since 1.5
  173.      */
  174.     function addCC($cc)
  175.     {
  176.         //If the carbon copy recipient is an aray, add each recipient... otherwise just add the one
  177.         if (isset ($cc))
  178.         {
  179.             if (is_array($cc)) {
  180.                 foreach ($cc as $to) {
  181.                     $to = JMailHelper::cleanLine( $to );
  182.                     parent::AddCC($to);
  183.                 }
  184.             } else {
  185.                 $cc = JMailHelper::cleanLine( $cc );
  186.                 parent::AddCC($cc);
  187.             }
  188.         }
  189.     }
  190.  
  191.     /**
  192.      * Add blind carbon copy recipients to the email
  193.      *
  194.      * @access public
  195.      * @param mixed $cc Either a string or array of strings [e-mail address(es)]
  196.      * @return void 
  197.      * @since 1.5
  198.      */
  199.     function addBCC($bcc)
  200.     {
  201.         // If the blind carbon copy recipient is an aray, add each recipient... otherwise just add the one
  202.         if (isset ($bcc))
  203.         {
  204.             if (is_array($bcc)) {
  205.                 foreach ($bcc as $to) {
  206.                     $to = JMailHelper::cleanLine( $to );
  207.                     parent::AddBCC($to);
  208.                 }
  209.             } else {
  210.                 $bcc = JMailHelper::cleanLine( $bcc );
  211.                 parent::AddBCC($bcc);
  212.             }
  213.         }
  214.     }
  215.  
  216.     /**
  217.      * Add file attachments to the email
  218.      *
  219.      * @access public
  220.      * @param mixed $attachment Either a string or array of strings [filenames]
  221.      * @return void 
  222.      * @since 1.5
  223.      */
  224.     function addAttachment($attachment)
  225.     {
  226.         // If the file attachments is an aray, add each file... otherwise just add the one
  227.         if (isset ($attachment))
  228.         {
  229.             if (is_array($attachment)) {
  230.                 foreach ($attachment as $file) {
  231.                     parent::AddAttachment($file);
  232.                 }
  233.             } else {
  234.                 parent::AddAttachment($attachment);
  235.             }
  236.         }
  237.     }
  238.  
  239.     /**
  240.      * Add Reply to e-mail address(es) to the e-mail
  241.      *
  242.      * @access public
  243.      * @param array $reply Either an array or multi-array of form
  244.      *          <pre>
  245.      *              array( [0] => E-Mail Address [1] => Name )
  246.      *          </pre>
  247.      * @return void 
  248.      * @since 1.5
  249.      */
  250.     function addReplyTo($replyto)
  251.     {
  252.         // Take care of reply email addresses
  253.         if (is_array($replyto[0]))
  254.         {
  255.             foreach ($replyto as $to) {
  256.                 $to0 = JMailHelper::cleanLine( $to[0] );
  257.                 $to1 = JMailHelper::cleanLine( $to[1] );
  258.                 parent::AddReplyTo($to0, $to1);
  259.             }
  260.         } else {
  261.             $replyto0 = JMailHelper::cleanLine( $replyto[0] );
  262.             $replyto1 = JMailHelper::cleanLine( $replyto[1] );
  263.             parent::AddReplyTo($replyto0, $replyto1);
  264.         }
  265.     }
  266.  
  267.     /**
  268.      * Use sendmail for sending the e-mail
  269.      *
  270.      * @access public
  271.      * @param string $sendmail Path to sendmail [optional]
  272.      * @return boolean True on success
  273.      * @since 1.5
  274.      */
  275.     function useSendmail($sendmail = null)
  276.     {
  277.         $this->Sendmail = $sendmail;
  278.  
  279.         if (!empty ($this->Sendmail)) {
  280.             $this->IsSendmail();
  281.             return true;
  282.         } else {
  283.             $this->IsMail();
  284.             return false;
  285.         }
  286.     }
  287.  
  288.     /**
  289.      * Use SMTP for sending the e-mail
  290.      *
  291.      * @access public
  292.      * @param string $auth SMTP Authentication [optional]
  293.      * @param string $host SMTP Host [optional]
  294.      * @param string $user SMTP Username [optional]
  295.      * @param string $pass SMTP Password [optional]
  296.      * @return boolean True on success
  297.      * @since 1.5
  298.      */
  299.     function useSMTP($auth = null, $host = null, $user = null, $pass = null)
  300.     {
  301.         $this->SMTPAuth = $auth;
  302.         $this->Host     = $host;
  303.         $this->Username = $user;
  304.         $this->Password = $pass;
  305.  
  306.         if ($this->SMTPAuth !== null && $this->Host !== null && $this->Username !== null && $this->Password !== null) {
  307.             $this->IsSMTP();
  308.             return true;
  309.         } else {
  310.             $this->IsMail();
  311.             return false;
  312.         }
  313.     }
  314. }
  315.  
  316. /**
  317.  * E-Mail helper class, provides static methods to perform various tasks relevant
  318.  * to the Joomla e-mail routines.
  319.  *
  320.  * TODO: Test these methods as the regex work is first run and not tested thoroughly
  321.  *
  322.  * @static
  323.  * @author         Louis Landry <[email protected]>
  324.  * @package     Joomla.Framework
  325.  * @subpackage        Utilities
  326.  * @since        1.5
  327.  */
  328. class JMailHelper
  329. {
  330.     /**
  331.      * Cleans single line inputs.
  332.      *
  333.      * @static
  334.      * @param string $value String to be cleaned.
  335.      * @return string Cleaned string.
  336.      */
  337.     function cleanLine( $value ) {
  338.         return trim( preg_replace( '/(%0A|%0D|\n+|\r+)/i', '', $value ) );
  339.     }
  340.  
  341.     /**
  342.      * Cleans multi-line inputs.
  343.      *
  344.      * @static
  345.      * @param string $value Multi-line string to be cleaned.
  346.      * @return string Cleaned multi-line string.
  347.      */
  348.     function cleanText( $value ) {
  349.         return trim( preg_replace( '/(%0A|%0D|\n+|\r+)(content-type:|to:|cc:|bcc:)/i', '', $value ) );
  350.     }
  351.  
  352.     /**
  353.      * Cleans any injected headers from the E-Mail body.
  354.      *
  355.      * @static
  356.      * @param string $body E-Mail body string.
  357.      * @return string Cleaned E-Mail body string.
  358.      * @since 1.5
  359.      */
  360.     function cleanBody($body) {
  361.         // Strip all E-Mail headers from a string
  362.         return preg_replace("/((From:|To:|Cc:|Bcc:|Subject:|Content-type:) ([\S]+))/", "", $body);
  363.     }
  364.  
  365.     /**
  366.      * Cleans any injected headers from the subject string.
  367.      *
  368.      * @static
  369.      * @param string $subject E-Mail subject string.
  370.      * @return string Cleaned E-Mail subject string.
  371.      * @since 1.5
  372.      */
  373.     function cleanSubject($subject) {
  374.         return preg_replace("/((From:|To:|Cc:|Bcc:|Content-type:) ([\S]+))/", "", $subject);
  375.     }
  376.  
  377.     /**
  378.      * Verifies that an e-mail address does not have any extra headers injected into it.
  379.      *
  380.      * @static
  381.      * @param string $address E-Mail address.
  382.      * @return string|falseE-Mail address string or boolean false if injected headers are present.
  383.      * @since 1.5
  384.      */
  385.     function cleanAddress($address)
  386.     {
  387.         if (preg_match("[\s;,]", $address)) {
  388.             return false;
  389.         }
  390.         return $address;
  391.     }
  392.  
  393.     /**
  394.      * Verifies that the string is in a proper e-mail address format.
  395.      *
  396.      * @static
  397.      * @param string $email String to be verified.
  398.      * @return boolean True if string has the correct format; false otherwise.
  399.      * @since 1.5
  400.      */
  401.     function isEmailAddress($email) {
  402.         $rBool = false;
  403.  
  404.         if (preg_match("/[\w\.\-]+@\w+[\w\.\-]*?\.\w{1,4}/", $email)) {
  405.             $rBool = true;
  406.         }
  407.         return $rBool;
  408.     }
  409.     
  410. }
  411. ?>
Documentation generated on Mon, 05 Mar 2007 21:10:05 +0000 by phpDocumentor 1.3.1