Joomla Platform  13.1
Documentation des API du framework Joomla Platform
 Tout Classes Espaces de nommage Fichiers Fonctions Variables Pages
mail.php
Aller à la documentation de ce fichier.
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 }