diff options
| -rw-r--r-- | includes/mail.inc | 162 | ||||
| -rw-r--r-- | modules/simpletest/drupal_web_test_case.php | 26 | ||||
| -rw-r--r-- | modules/simpletest/simpletest.info | 1 | ||||
| -rw-r--r-- | modules/simpletest/tests/mail.test | 51 | ||||
| -rw-r--r-- | modules/system/mail.sending.inc | 62 | ||||
| -rw-r--r-- | modules/system/system.info | 1 |
6 files changed, 231 insertions, 72 deletions
diff --git a/includes/mail.inc b/includes/mail.inc index e2dbd15f6..912d64359 100644 --- a/includes/mail.inc +++ b/includes/mail.inc @@ -2,6 +2,11 @@ // $Id$ /** + * @file + * API functions for processing and sending e-mail. + */ + +/** * Compose and optionally send an e-mail message. * * Sending an e-mail works with defining an e-mail template (subject, text @@ -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); } /** diff --git a/modules/simpletest/drupal_web_test_case.php b/modules/simpletest/drupal_web_test_case.php index 822a92a15..41abb195c 100644 --- a/modules/simpletest/drupal_web_test_case.php +++ b/modules/simpletest/drupal_web_test_case.php @@ -1103,9 +1103,8 @@ class DrupalWebTestCase extends DrupalTestCase { 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 @@ class DrupalWebTestCase extends DrupalTestCase { 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 @@ class DrupalWebTestCase extends DrupalTestCase { * 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 @@ class DrupalWebTestCase extends DrupalTestCase { * 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 @@ class DrupalWebTestCase extends DrupalTestCase { $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; } /** diff --git a/modules/simpletest/simpletest.info b/modules/simpletest/simpletest.info index 9d307eb5b..ad42f17c4 100644 --- a/modules/simpletest/simpletest.info +++ b/modules/simpletest/simpletest.info @@ -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 diff --git a/modules/simpletest/tests/mail.test b/modules/simpletest/tests/mail.test new file mode 100644 index 000000000..641d606ff --- /dev/null +++ b/modules/simpletest/tests/mail.test @@ -0,0 +1,51 @@ +<?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; + } +} + diff --git a/modules/system/mail.sending.inc b/modules/system/mail.sending.inc new file mode 100644 index 000000000..6533de07d --- /dev/null +++ b/modules/system/mail.sending.inc @@ -0,0 +1,62 @@ +<?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; + } +} + diff --git a/modules/system/system.info b/modules/system/system.info index 8eb7db900..fa9a77d59 100644 --- a/modules/system/system.info +++ b/modules/system/system.info @@ -12,4 +12,5 @@ files[] = system.install files[] = system.test files[] = system.tar.inc files[] = system.tokens.inc +files[] = mail.sending.inc required = TRUE |