Commit ee59107c authored by webchick's avatar webchick

#331180 by pwolanin and Rob Loach: Added pluggable smtp/mail framework.

parent 701d0652
<?php
// $Id$
/**
* @file
* API functions for processing and sending e-mail.
*/
/**
* Compose and optionally send an e-mail message.
*
......@@ -61,10 +66,10 @@
* @param $to
* The e-mail address or addresses where the message will be sent to. The
* formatting of this string must comply with RFC 2822. Some examples are:
* user@example.com
* user@example.com, anotheruser@example.com
* User <user@example.com>
* User <user@example.com>, Another User <anotheruser@example.com>
* - user@example.com
* - user@example.com, anotheruser@example.com
* - User <user@example.com>
* - User <user@example.com>, Another User <anotheruser@example.com>
* @param $language
* Language object to use to compose the e-mail.
* @param $params
......@@ -127,7 +132,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N
// Optionally send e-mail.
if ($send) {
$message['result'] = drupal_mail_send($message);
$message['result'] = drupal_mail_sending_system($module, $key)->mail($message);
// Log errors
if (!$message['result']) {
......@@ -140,58 +145,113 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N
}
/**
* Send an e-mail message, using Drupal variables and default settings.
* More information in the <a href="http://php.net/manual/en/function.mail.php">
* PHP function reference for mail()</a>. See drupal_mail() for information on
* how $message is composed.
* Returns an object that implements the MailSystemInterface.
*
* @param $message
* Message array with at least the following elements:
* - id
* A unique identifier of the e-mail type. Examples: 'contact_user_copy',
* 'user_password_reset'.
* - to
* The mail address or addresses where the message will be sent to. The
* formatting of this string must comply with RFC 2822. Some examples are:
* user@example.com
* user@example.com, anotheruser@example.com
* User <user@example.com>
* User <user@example.com>, Another User <anotheruser@example.com>
* - subject
* Subject of the e-mail to be sent. This must not contain any newline
* characters, or the mail may not be sent properly.
* - body
* Message to be sent. Accepts both CRLF and LF line-endings.
* E-mail bodies must be wrapped. You can use drupal_wrap_mail() for
* smart plain text wrapping.
* - headers
* Associative array containing all mail headers.
* @return
* Returns TRUE if the mail was successfully accepted for delivery,
* FALSE otherwise.
* Allows for one or more custom mail backends to send mail messages
* composed using drupal_mail().
*
* The selection of a particular implementation is controlled via the variable
* 'mail_sending_system', which is a keyed array. The default implementation
* is the class whose name is the value of 'default-system' key. A more specific
* match first to key and then to module will be used in preference to the
* default. To specificy a different class for all mail sent by one module, set
* the class name as the value for the key corresponding to the module name. To
* specificy a class for a particular message sent by one module, set the class
* name as the value for the array key that is the message id, which is
* "${module}_${key}".
*
* For example to debug all mail sent by the user module by logging it to a
* file, you might set the variable as something like:
*
* @code
* array(
* 'default-system' => 'DrupalMailSend',
* 'user' => 'DevelMailLog',
* );
* @endcode
*
* Finally, a different system can be specified for a specific e-mail ID (see
* the $key param), such as one of the keys used by the contact module:
*
* @code
* array(
* 'default-system' => 'DrupalMailSend',
* 'user' => 'DevelMailLog',
* 'contact_page_autoreply' => 'DrupalDevNullMailSend',
* );
* @endcode
*
* Other possible uses for system include a mail-sending class that actually
* sends (or duplicates) each message to SMS, Twitter, instant message, etc, or
* a class that queues up a large number of messages for more efficient bulk
* sending or for sending via a remote gateway so as to reduce the load
* on the local server.
*
* @param $module
* The module name which was used by drupal_mail() to invoke hook_mail().
* @param $key
* A key to identify the e-mail sent. The final e-mail ID for the e-mail
* alter hook in drupal_mail() would have been {$module}_{$key}.
*/
function drupal_mail_send($message) {
// Allow for a custom mail backend.
if (variable_get('smtp_library', '') && file_exists(variable_get('smtp_library', ''))) {
include_once DRUPAL_ROOT . '/' . variable_get('smtp_library', '');
return drupal_mail_wrapper($message);
function drupal_mail_sending_system($module, $key) {
$instances = &drupal_static(__FUNCTION__, array());
$id = $module . '_' . $key;
$configuration = variable_get('mail_sending_system', array('default-system' => 'DrupalMailSend'));
// Look for overrides for the default class, starting from the most specific
// id, and falling back to the module name.
if (isset($configuration[$id])) {
$class = $configuration[$id];
}
elseif (isset($configuration[$module])) {
$class = $configuration[$module];
}
else {
$mimeheaders = array();
foreach ($message['headers'] as $name => $value) {
$mimeheaders[] = $name . ': ' . mime_header_encode($value);
$class = $configuration['default-system'];
}
if (empty($instances[$class])) {
$interfaces = class_implements($class);
if (isset($interfaces['MailSystemInterface'])) {
$instances[$class] = new $class;
}
else {
throw new Exception(t('Class %class does not implement interface %interface', array('%class' => $class, '%interface' => 'MailSystemInterface')));
}
return mail(
$message['to'],
mime_header_encode($message['subject']),
// Note: e-mail uses CRLF for line-endings, but PHP's API requires LF.
// They will appear correctly in the actual e-mail that is sent.
str_replace("\r", '', $message['body']),
// For headers, PHP's API suggests that we use CRLF normally,
// but some MTAs incorrectly replace LF with CRLF. See #234403.
join("\n", $mimeheaders)
);
}
return $instances[$class];
}
/**
* An interface for pluggable mail back-ends.
*/
interface MailSystemInterface {
/**
* Send an e-mail message composed by drupal_mail().
*
* @param $message
* Message array with at least the following elements:
* - id: A unique identifier of the e-mail type. Examples: 'contact_user_copy',
* 'user_password_reset'.
* - to: The mail address or addresses where the message will be sent to.
* The formatting of this string must comply with RFC 2822. Some examples:
* - user@example.com
* - user@example.com, anotheruser@example.com
* - User <user@example.com>
* - User <user@example.com>, Another User <anotheruser@example.com>
* - subject: Subject of the e-mail to be sent. This must not contain any
* newline characters, or the mail may not be sent properly.
* - body: Message to be sent. Accepts both CRLF and LF line-endings.
* E-mail bodies must be wrapped. You can use drupal_wrap_mail() for
* smart plain text wrapping.
* - headers: Associative array containing all additional mail headers not
* defined by one of the other parameters. PHP's mail() looks for Cc
* and Bcc headers and sends the mail to addresses in these headers too.
* @return
* TRUE if the mail was successfully accepted for delivery, otherwise FALSE.
*/
public function mail(array $message);
}
/**
......
......@@ -1103,9 +1103,8 @@ protected function setUp() {
unset($GLOBALS['conf']['language_default']);
$language = language_default();
// Make sure our drupal_mail_wrapper function is called instead of the
// default mail handler.
variable_set('smtp_library', drupal_get_path('module', 'simpletest') . '/drupal_web_test_case.php');
// Use the test mail class instead of the default mail handler class.
variable_set('mail_sending_system', array('default-system' => 'TestingMailSystem'));
// Use temporary files directory with the same prefix as the database.
$public_files_directory = $this->originalFileDirectory . '/' . $db_prefix;
......@@ -1165,7 +1164,7 @@ protected function tearDown() {
simpletest_log_read($this->testId, $db_prefix, get_class($this), TRUE);
$db_prefix = $db_prefix_temp;
$emailCount = count(variable_get('simpletest_emails', array()));
$emailCount = count(variable_get('drupal_test_email_collector', array()));
if ($emailCount) {
$message = format_plural($emailCount, t('!count e-mail was sent during this test.'), t('!count e-mails were sent during this test.'), array('!count' => $emailCount));
$this->pass($message, t('E-mail'));
......@@ -1918,7 +1917,7 @@ protected function drupalGetContent() {
* An array containing e-mail messages captured during the current test.
*/
protected function drupalGetMails($filter = array()) {
$captured_emails = variable_get('simpletest_emails', array());
$captured_emails = variable_get('drupal_test_email_collector', array());
$filtered_emails = array();
foreach ($captured_emails as $message) {
......@@ -2475,7 +2474,7 @@ protected function assertResponse($code, $message = '') {
* TRUE on pass, FALSE on fail.
*/
protected function assertMail($name, $value = '', $message = '') {
$captured_emails = variable_get('simpletest_emails', array());
$captured_emails = variable_get('drupal_test_email_collector', array());
$email = end($captured_emails);
return $this->assertTrue($email && isset($email[$name]) && $email[$name] == $value, $message, t('E-mail'));
}
......@@ -2495,22 +2494,7 @@ protected function verbose($message) {
$this->pass(l(t('Verbose message'), $this->originalFileDirectory . '/simpletest/verbose/' . get_class($this) . '-' . $id . '.html', array('attributes' => array('target' => '_blank'))), 'Debug');
}
}
}
/**
* Wrapper function to override the default mail handler function.
*
* @param $message
* An e-mail message. See drupal_mail() for information on how $message is composed.
* @return
* Returns TRUE to indicate that the e-mail was successfully accepted for delivery.
*/
function drupal_mail_wrapper($message) {
$captured_emails = variable_get('simpletest_emails', array());
$captured_emails[] = $message;
variable_set('simpletest_emails', $captured_emails);
return TRUE;
}
/**
......
......@@ -25,6 +25,7 @@ files[] = tests/form.test
files[] = tests/graph.test
files[] = tests/image.test
files[] = tests/lock.test
files[] = tests/mail.test
files[] = tests/menu.test
files[] = tests/module.test
files[] = tests/registry.test
......
<?php
// $Id$
/**
* Test the Drupal mailing system.
*/
class MailTestCase extends DrupalWebTestCase implements MailSystemInterface {
/**
* The most recent message that was sent through the test case.
*
* We take advantage here of the fact that static variables are shared among
* all instance of the same class.
*/
private static $sent_message;
function getInfo() {
return array(
'name' => 'Mail system',
'description' => 'Performs tests on the pluggable mailing framework.',
'group' => 'System',
);
}
function setUp() {
parent::setUp();
// Set MailTestCase (i.e. this class) as the SMTP library
variable_set('mail_sending_system', array('default-system' => 'MailTestCase'));
}
/**
* Assert that the pluggable mail system is functional.
*/
function testPluggableFramework() {
global $language;
// Use MailTestCase for sending a message.
$message = drupal_mail('simpletest', 'mail_test', 'testing@drupal.org', $language);
// Assert whether the message was sent through the send function.
$this->assertEqual(self::$sent_message['to'], 'testing@drupal.org', t('Pluggable mail system is extendable.'));
}
/**
* Send function that is called through the mail system.
*/
public function mail(array $message) {
self::$sent_message = $message;
}
}
<?php
// $Id$
/**
* @file
* Drupal core implementations of the DrupalMailSendingInterface.
*/
/**
* The default Drupal mail sending library using PHP's mail function.
*/
class DefaultMailSystem implements MailSystemInterface {
/**
* Send an e-mail message, using Drupal variables and default settings.
* @see http://php.net/manual/en/function.mail.php the PHP function reference
* for mail().
* @see drupal_mail() for information on how $message is composed.
*
* @param $message
* Message array as described by DrupalMailSendingInterface.
* @return
* TRUE if the mail was successfully accepted, otherwise FALSE.
*/
public function mail(array $message) {
$mimeheaders = array();
foreach ($message['headers'] as $name => $value) {
$mimeheaders[] = $name . ': ' . mime_header_encode($value);
}
return mail(
$message['to'],
mime_header_encode($message['subject']),
// Note: e-mail uses CRLF for line-endings, but PHP's API requires LF.
// They will appear correctly in the actual e-mail that is sent.
str_replace("\r", '', $message['body']),
// For headers, PHP's API suggests that we use CRLF normally,
// but some MTAs incorrectly replace LF with CRLF. See #234403.
join("\n", $mimeheaders)
);
}
}
/**
* A mail sending implementation that captures sent messages to a variable.
*
* This class is for running tests or for development.
*/
class TestingMailSystem implements MailSystemInterface {
/**
* Accept an e-mail message and store it in a variable.
*
* @param $message
* An e-mail message.
*/
public function mail(array $message) {
$captured_emails = variable_get('drupal_test_email_collector', array());
$captured_emails[] = $message;
variable_set('drupal_test_email_collector', $captured_emails);
return TRUE;
}
}
......@@ -12,4 +12,5 @@ files[] = system.install
files[] = system.test
files[] = system.tar.inc
files[] = system.tokens.inc
files[] = mail.sending.inc
required = TRUE
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment