From bc28adfd1ac9649400c571a274968061acb526bb Mon Sep 17 00:00:00 2001 From: Bob Vincent Date: Tue, 30 Aug 2011 12:41:35 -0400 Subject: [PATCH] Issue #800434 by bart.hanssens, sun, pillarsdotnet, larowlan, plach: Allow hook_mail_alter() implementations to cancel mail sending. --- includes/mail.inc | 63 +++++++++++++++++++++++++-------- modules/simpletest/simpletest.module | 13 +++++++ modules/simpletest/tests/mail.test | 24 +++++++++++-- modules/system/system.api.php | 11 +++++- 4 files changed, 91 insertions(+), 20 deletions(-) diff --git a/includes/mail.inc b/includes/mail.inc index 7272df972e2970f1faeb0aa050ae3758fff93777..d30d1988e20c91929b66409f0afa4cf711f65497 100644 --- a/includes/mail.inc +++ b/includes/mail.inc @@ -57,6 +57,12 @@ define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER * user_mail_tokens($variables, $data, $options); * switch($key) { * case 'notice': + * // If the recipient can receive such notices by instant-message, + * // do not send by email. + * if (example_im_send($key, $message, $params)) { + * $message['send'] = FALSE; + * break; + * } * $langcode = $message['language']->language; * $message['subject'] = t('Notification from !site', $variables, array('langcode' => $langcode)); * $message['body'][] = t("Dear !username\n\nThere is new content available on the site.", $variables, array('langcode' => $langcode)); @@ -65,13 +71,26 @@ define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER * } * @endcode * + * Another example, which uses drupal_mail() to format a message for sending + * later: + * + * @code + * $params = array('current_conditions' => $data); + * $to = 'user@example.com'; + * $message = drupal_mail('example', 'notice', $to, $language, $params, FALSE); + * // Only add to the spool if sending was not canceled. + * if ($message['send']) { + * example_spool_message($message); + * } + * @endcode + * * @param $module - * A module name to invoke hook_mail() on. The {$module}_mail() hook will be - * called to complete the $message structure which will already contain common - * defaults. + * The name of the module implementing hook_mail(). This callback may use + * information from $params to modify the default $message structure before + * hook_mail_alter() is invoked. * @param $key - * A key to identify the e-mail sent. The final e-mail id for e-mail altering - * will be {$module}_{$key}. + * A key to identify the e-mail sent. This is combined with the $module + * parameter and made available as $message['id'] = $module . '_' . $key. * @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: @@ -82,12 +101,15 @@ define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER * @param $language * Language object to use to compose the e-mail. * @param $params - * Optional parameters to build the e-mail. + * An associative array with string keys, which will be passed to the + * hook_mail() function implemented by the $module module, if it exists. * @param $from * Sets From to this value, if given. * @param $send - * Send the message directly, without calling drupal_mail_system()->mail() - * manually. + * If TRUE, drupal_mail() will call drupal_mail_system()->mail() to deliver + * the message, and store the result in $message['result']. Modules + * implementing hook_mail_alter() may cancel sending by setting + * $message['send'] to FALSE. * * @return * The $message array structure containing all details of the @@ -108,6 +130,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N 'from' => isset($from) ? $from : $default_from, 'language' => $language, 'params' => $params, + 'send' => TRUE, 'subject' => '', 'body' => array() ); @@ -148,12 +171,20 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N // Optionally send e-mail. if ($send) { - $message['result'] = $system->mail($message); - - // Log errors - if (!$message['result']) { - watchdog('mail', 'Error sending e-mail (from %from to %to).', array('%from' => $message['from'], '%to' => $message['to']), WATCHDOG_ERROR); - drupal_set_message(t('Unable to send e-mail. Contact the site administrator if the problem persists.'), 'error'); + // The original caller requested sending. + if (empty($message['send'])) { + // Sending was canceled by one or more hook_mail_alter() implementations. + // We set 'result' to NULL, because FALSE indicates an error in sending. + $message['result'] = NULL; + } + else { + // Sending was originally requested and was not cancelled. + $message['result'] = $system->mail($message); + // Log errors. + if (!$message['result']) { + watchdog('mail', 'Error sending e-mail (from %from to %to).', array('%from' => $message['from'], '%to' => $message['to']), WATCHDOG_ERROR); + drupal_set_message(t('Unable to send e-mail. Contact the site administrator if the problem persists.'), 'error'); + } } } @@ -179,7 +210,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N * DefaultMailSystem implementation. * * The selection of a particular implementation is controlled via the variable - * 'mail_system', which is a keyed array. The default implementation + * 'mail_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 @@ -288,7 +319,7 @@ interface MailSystemInterface { * 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 + * 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 diff --git a/modules/simpletest/simpletest.module b/modules/simpletest/simpletest.module index 310dc3582b41a7d2c6d636b2ef0cd80fe2456e59..6292cfc81414184d69b13fde70b05d90c0c2e85d 100644 --- a/modules/simpletest/simpletest.module +++ b/modules/simpletest/simpletest.module @@ -504,3 +504,16 @@ function simpletest_clean_results_table($test_id = NULL) { } return 0; } + +/** + * Implements hook_mail_alter(). + * + * Aborts sending of messages with id 'simpletest_cancel_test'. + * + * @see MailTestCase::testCancelMessage() + */ +function simpletest_mail_alter(&$message) { + if ($message['id'] == 'simpletest_cancel_test') { + $message['send'] = FALSE; + } +} diff --git a/modules/simpletest/tests/mail.test b/modules/simpletest/tests/mail.test index a6c7b40e5ef3b2eb46fb79be440ddf39ddb3787c..585e2d2a143230416a72d277bc4af92422be3e27 100644 --- a/modules/simpletest/tests/mail.test +++ b/modules/simpletest/tests/mail.test @@ -22,7 +22,7 @@ class MailTestCase extends DrupalWebTestCase implements MailSystemInterface { } function setUp() { - parent::setUp(); + parent::setUp(array('simpletest')); // Set MailTestCase (i.e. this class) as the SMTP library variable_set('mail_system', array('default-system' => 'MailTestCase')); @@ -35,10 +35,28 @@ class MailTestCase extends DrupalWebTestCase implements MailSystemInterface { global $language; // Use MailTestCase for sending a message. - $message = drupal_mail('simpletest', 'mail_test', 'testing@drupal.org', $language); + $message = drupal_mail('simpletest', 'mail_test', 'testing@example.com', $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.')); + $this->assertEqual(self::$sent_message['to'], 'testing@example.com', t('Pluggable mail system is extendable.')); + } + + /** + * Test that message sending may be canceled. + * + * @see simpletest_mail_alter() + */ + function testCancelMessage() { + global $language; + + // Reset the class variable holding a copy of the last sent message. + self::$sent_message = NULL; + + // Send a test message that simpletest_mail_alter should cancel. + $message = drupal_mail('simpletest', 'cancel_test', 'cancel@example.com', $language); + + // Assert that the message was not actually sent. + $this->assertNull(self::$sent_message, 'Message was cancelled.'); } /** diff --git a/modules/system/system.api.php b/modules/system/system.api.php index d040ab39834aae9dec5955f96810e0293e5c343f..b2058384fefdd1e5aa35f42390153780297d4421 100644 --- a/modules/system/system.api.php +++ b/modules/system/system.api.php @@ -1422,7 +1422,7 @@ function hook_image_toolkits() { * invoke hook_mail_alter(). For example, a contributed module directly * calling the drupal_mail_system()->mail() or PHP mail() function * will not invoke this hook. All core modules use drupal_mail() for - * messaging, it is best practice but not mandatory in contributed modules. + * messaging; it is best practice but not mandatory in contributed modules. * * @param $message * An array containing the message data. Keys in this array include: @@ -1451,11 +1451,20 @@ function hook_image_toolkits() { * - 'language': * The language object used to build the message before hook_mail_alter() * is invoked. + * - 'send': + * Set to FALSE to abort sending this email message. * * @see drupal_mail() */ function hook_mail_alter(&$message) { if ($message['id'] == 'modulename_messagekey') { + if (!example_notifications_optin($message['to'], $message['id'])) { + // If the recipient has opted to not receive such messages, cancel + // sending. This kind of check can be done once in a hook_mail_alter() + // implementation rather than patching all possible sending modules. + $message['send'] = FALSE; + return; + } $message['body'][] = "--\nMail sent out from " . variable_get('sitename', t('Drupal')); } } -- 1.7.5.4