function drupal_set_message

You are here

7 bootstrap.inc drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE)
4.6 bootstrap.inc drupal_set_message($message = NULL, $type = 'status')
4.7 bootstrap.inc drupal_set_message($message = NULL, $type = 'status')
5 bootstrap.inc drupal_set_message($message = NULL, $type = 'status')
6 bootstrap.inc drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE)
8 bootstrap.inc drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE)

Sets a message to display to the user.

Messages are stored in a session variable and displayed in page.tpl.php via the $messages theme variable.

Example usage:

drupal_set_message(t('An error occurred and processing did not complete.'), 'error');

Parameters

string $message: (optional) The translated message to be displayed to the user. For consistency with other messages, it should begin with a capital letter and end with a period.

string $type: (optional) The message's type. Defaults to 'status'. These values are supported:

  • 'status'
  • 'warning'
  • 'error'

bool $repeat: (optional) If this is FALSE and the message is already set, then the message won't be repeated. Defaults to TRUE.

Return value

array|null A multidimensional array with keys corresponding to the set message types. The indexed array values of each contain the set messages for that type. Or, if there are no messages set, the function returns NULL.

See also

drupal_get_messages()

theme_status_messages()

265 calls to drupal_set_message()

File

includes/bootstrap.inc, line 1777
Functions that need to be loaded on every Drupal request.

Code

function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) {
  if ($message) {
    if (!isset($_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type] = array();
    }

    if ($repeat || !in_array($message, $_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type][] = $message;
    }

    // Mark this page as being uncacheable.
    drupal_page_is_cacheable(FALSE);
  }

  // Messages not set when DB connection fails.
  return isset($_SESSION['messages']) ? $_SESSION['messages'] : NULL;
}

Comments

You can use

drupal_get_messages('status');

to clear all status messages and leave errors intact.

This function does not automatically translate messages so it is important to translate them first, e.g.:

<?php
  drupal_set_message
(t("Don't panic!"), 'warning');
?>

It'd be nice if drupal_set_message had t() built in a la watchdog.

drupal_set_message($message = NULL, $args = NULL, $type = 'status', $repeat = TRUE)

drupal_set_message('Hello :name', array(':name' => $name));

Just a thought.

I'd agree, maybe this should be raised as a feature request. As drupal_set_message is fairly widely-used it's unlikely to be changed in a minor release, but maybe a future major version could incorporate this?

As both 'type' and 'args' would be optional, maybe it be worth moving over to a single url() style 'options' argument:

<?php
drupal_set_message
($message = NULL, $options = array()) {
 
// Merge in defaults.
 
$options += array(
   
'args' => array(),
   
'type' => 'status',
   
'repeat' => TRUE,
  );
 
// ...
}
?>

I agree too. Also drupal_set_message() uses hardcoded strings like 'warning' for the type, where constants would have been much better. In fact drupal_set_message() and watchdog() could be merged into a single function, with an option to set the message either in the UI, like drupal_set_message() or allowing the logging to be handled by another module like watchdog.

Note that the $type parameter can be anything you like and is passed directly through to the rendered div's class attribute. For example the following:

drupal_set_message(t('Something horrible just happened.'),'nuke');

generates this HTML:
<div class="messages nuke"> Something horrible just happened.</div>

Which can be styled with the following CSS:

div.nuke, table tr.nuke {
    background-color: #FF5EBE;
}
div.nuke, .nuke {
    color: #6B3A61;
}
div.nuke {
    background-image: url("nuke.png");
    border-color: #FFFA00;
}

Be sure the background image "nuke.png" above is 24x24 pixels which will ensure the borders and padding work out nicely.

Do meet Drupal standards and to ensure that everything is done securely this should be implemented as:

drupal_set_message(check_plain(t('Something !var just happened.'), array('!var' => $horrible)),'nuke');

@CarlHinton and coding standards:

<?php
drupal_set_message
(t('Something @var just happened.'), array('@var' => $horrible), 'nuke');
?>

Would probably be a better choice, since @ does a check_plain for you. Also see: format_string

Your code returns a compile time error:

Warning: Illegal offset type in drupal_set_message() (line 1785 of /site/includes/bootstrap.inc).

The brackets were just in the wrong place. Try this one:

<?php
drupal_set_message
(t('Something @var just happened.', array('@var' => $pleasant)), 'butterflies');
?>

To alter messages, e.g., hide the "Further instructions have been sent to you by email", see http://stackoverflow.com/questions/4942785/alter-messages-in-drupal-7, or https://drupal.org/node/162697.

This is how it works:

<?php
function mymodule_preprocess_status_messages(&$variables) {
 
//dpm(drupal_get_messages($variables['display']));
 
$message = 'Further instructions have been sent to your e-mail address.';
  if (isset(
$_SESSION['messages'])) {
    foreach (
$_SESSION['messages'] as $type => $messages) {
      if (
$type == 'status') {
       
$pos = array_search($message, $messages);
        if (
$pos !== FALSE) {
          unset(
$_SESSION['messages'][$type][$pos]);
        }
      }
    }
  }
}
?>

Thanks for the simple example! I just wanted to add that hook_preprocess_status_messages happens after watchdog has already heard of it. You might be getting clever and silencing or changing some PHP Notices, for instance, but they'll still clutter watchdog.